@graview/core
@graview/core is one of the 14 npm packages of Graview, a TypeScript framework that derives an app’s interface, permissions and agent tools from one declaration. The graph, the log, the schema and the checker. Everything a Graview app declares, and the CLI that verifies it.
pnpm add @graview/coreEntry points: @graview/core, @graview/core/document, @graview/core/compiled, @graview/core/retry, @graview/core/describe, @graview/core/figures, @graview/core/scene, @graview/core/city, @graview/core/check, @graview/core/blocks, @graview/core/arrange, @graview/core/shown, @graview/core/record-boxes, @graview/core/head, @graview/core/revisions, @graview/core/csv, @graview/core/navigate, @graview/core/provenance, @graview/core/history, @graview/core/past, @graview/core/linked, @graview/core/tidying, @graview/core/catalog, @graview/core/jobs, @graview/core/devices, @graview/core/workflows, @graview/core/friction, @graview/core/css, @graview/core/learn, @graview/core/told, @graview/core/compose, @graview/core/composer, @graview/core/traits, @graview/core/subscriptions, @graview/core/markdown, @graview/core/words, @graview/core/seat, @graview/core/binding, @graview/core/publishing, @graview/core/field-sight, @graview/core/typing, @graview/core/search, @graview/core/forms, @graview/core/lines, @graview/core/json-schema, @graview/core/sync, @graview/core/import, @graview/core/snapshot, @graview/core/conformance, @graview/core/sqlite, @graview/core/scaffold, @graview/core/cli, @graview/core/testing, @graview/core/typed, @graview/core/document.schema.json
What it is
Everything a Graview app declares, and the checker that verifies it.
- Schema —
defineNodeandcreateSchema. Zod is the single source of runtime validation, TypeScript types and JSON Schema. - Graph — nodes and edges, with a tracked reader so a mutation records what it read as well as what it wrote.
- Mutations —
defineMutation. Every change is a typed, named, describable act; nothing writes the graph directly. Each kind gets a derivededit-<kind>offering the fields no other act writes. Every act refuses an argument it does not take, naming those it does, and an act refused as asked throws anActRefusalwhosereasonandsentencea host can show (refusalOfreads one):refusedwhen the act's own rule says no,invalidfor the call as sent. - Invariants — rules that judge the graph and name the mutations that would repair them. That naming is the seam derived affordances ride on.
- Operation log — the graph is a fold over it. Author, intent, reads and writes on every op, which is what makes selective undo a dependency question rather than a stack.
- Permissions — a
Principalis anAuthorwith roles, so what the log blames is what the policy judged. - Files — a record holds a picture, a video or a document the host stored (
imageField,videoField,fileField;"image","video"and"file"in a document, and a list of any): aFileValue, itshrefa path on the host, uploaded through the page'sHostFilesand drawn where the host serves it (fileSrc). A video's value may say itsposter, itsdurationin seconds and itscaptions(a WebVTT file on the host), and is said "a 45-second video" (videoWords). - Theme — the token contract, the two shipped palettes, and a contrast checker that measures a brand's palette before it ships. The rest of the look is data beside them —
SHAPE,TYPOGRAPHYandisoShade(scheme), resolved for a brand byshapeOfandtypographyOf— so a page outside the app can dress as one without importing a stylesheet. A document's brand holds the rest of it too (FR-124): a logo and a page icon, judged bysvgProblemandmarkProblemunder the same rules as Graview Cloud's images; faces named fromSYSTEM_STACKS, the system's own andDOCUMENT_FONTS, judged byfontProblem; and an accent that does not read as given is refused byaccentProblemwith the pair, its ratio and a shade that would pass (FR-126). Graview's own identity (the design kit, revision 03) is data too, and reaches an app only through these defaults:GRAVIEW_COLORS(En Dash navy and turquoise, paper, reading ink, muted text),GRAVIEW_FACEandWEIGHTS(Montserrat at 550, 450 and 600, named first inTYPOGRAPHYand never fetched),LOGO_RULES, and the shared-plane symbol as an inline currentColor SVG (graviewSymbol, the micro cut under 28 px bysymbolCut). The shipped palettes are built on it; turquoise is in neither, since it is a point and a fill, never text. graview check— reads a declaration and reports what is wrong with it, in terms an agent can act on. In code it is@graview/core/check:checkApp,describeApp, the agent docs (generateLlmsTxt), andcompileDocument, a document compiled and checked.- Documents —
@graview/core/document: a whole app as one JSON object, compiled bycompileDocumentWithoutCheckinto the same appdefineAppdeclares and never run as code (compileDocumentfrom@graview/core/checkalso asks the checker);toDocumentwrites an app back out. Rules say what must hold in a small, budgeted language (expressionRule). Every command that takes an entry takes--document <file>. A view's blocks resolve with@graview/core/blocks. A number field may say its range (min,max,step), which every form, tool and apply honors; an act'sconnectslinks from whichever end of the relation its subject is,replacessevers the links it supersedes and set the record at the other end (its "setsOther" key), and its "setsLinked" key carries a change to the records its subject is already linked to through a relation, judged by each far record's own edit.editDocument,diffDocumentsandplanMigrationchange a document and say what the change does to stored data. A host that compiles a document on its server hands the pageserializeCompiled(compiled), and the page builds the same app withappFromorappFromOrCompilefrom@graview/core/compiled, which carries no compiler (the format isgraview-compiled@1). - A document's shape, for an editor and a compiler — every version ships
@graview/core/document.schema.json, the document format as JSON Schema, written by the build from the shape the compiler reads. A document that says"$schema": "./node_modules/@graview/core/dist/document.schema.json"(or the version's own address, its$id) is checked as it is typed: an unknown key is underlined in the editor, not refused at run time.@graview/core/typedis the same document in TypeScript:defineDocumentreturns the JSON document unchanged, and a key the format does not have, an edge to a kind nobody declares, a glance or lifecycle field the kind lacks, a relation an act connects or a kind a rule is over that is not declared is a type error.graview types <document> --out document.d.tswrites a document's kinds, fields (an enum's options as a union) and relations as types,TypesOf<typeof document>derives the same from adefineDocument, andtypedReader<Types>(store)reads a store through them (reader.fieldOf(node, "status"),reader.edgesOf(node, "under")and the rest), so a renamed field or relation failstscin the product that reads it. - A part that tries again —
@graview/core/retry, for a page only:retryingImport(() => import("./part.js"))is a loader that asks again after the import failed, with a URL of its own (?retry=<n>) where the engine keeps a failed module for the page's life, as Chromium and Firefox do. Never from a server's code: workerd refuses a script with a computedimport()in it. - A snapshot file —
@graview/core/snapshot:writeSnapshot(graph)writes a header line (when it was made, records and links per kind, where each kind's lines are) and then a record per line; `readSnapshot(text, { kinds })parses only the kinds asked for,fetchSnapshot(url, { kinds })` fetches only their bytes, and an old{ nodes, edges }file still reads. - Two-way sync —
@graview/core/sync:SyncEngineover the op log, with a conflict policy (report,theirs,ours), resources the remote owns (readonly, refused here with theirbecause), links seeded from a version field, and transports for Google Calendar and for a tool server over MCP (mcpClient,mcpDoor,doorClient,mcpRemote). The Google transport follows every page, starts a full resync when Google rejects the sync token, and askstoken({ refresh: true })once when Google refuses an access token;scripts/verify-google-calendar.mjsproves it against a real test calendar (credentials from~/.graview-google-test.env, made once byscripts/google-calendar-once.mjs;scripts/calendar-sync-demo.mjsis the same by hand). A Notion database is a transport too (notion): one database, one kind, property to field by name or as declared, pulled bylast_edited_timeacross every page of a query, pages made, set and archived, Notion's rate limit waited out, and a refused secret or an unshared database said as a sentence;scriptedNotion()is a Notion in memory to test against, andscripts/verify-notion.mjsproves the transport against a real workspace (~/.graview-notion-test.env;--stubagainst the scripted one). A document declares either asconnections.<name>— a calendar, its fields and a color or tag filter, or a database and its properties;readorboth, the conflict policy — judged bygraview checkand run bygraview serveand `graview preview;connection(…)` builds its engine for any host. - A spreadsheet brought in —
@graview/core/import: `importRows(store, kind, rows, mapping, { by })` reads each cell by its field's type, links a cell to a record by its name, keeps every row that fits as one undoable batchvia: "import", and says each refused row in words;previewImportkeeps nothing,proposeMappingoffers a mapping from the header row, andparseCsvreads a CSV or a paste (docs/import.md). - The city —
@graview/core/scene:sceneThumbnaildraws a document (or an app) as the Scene draws it from altitude — the same districts on the same map, in their hues — as one SVG string, with no DOM, for a host listing apps;sceneDistrictsis the same answer as data. At a card's size,fit: "content"fits it to what stands: each district on its whole block from the same corner, cropped to the plots, with a few blocks no narrower thanminBuildingpixels (16 by default) rather than a speck per record. Without counts — a live app with no snapshot — each district stands three blocks placed and raised by its kind's name, so every app still looks like itself.size: "icon"draws it as a tab's icon: 32 by 32, each district on its block in its hue with one block on it, readable at 16 pixels and about a kilobyte — a standalone SVG to serve as a favicon. A kind's figures are@graview/core/figures. - What is said, matched and listed after a page draws (FR-179) —
@graview/core/search: the one matcher (search,actsOn,touchWeights,parseQuery,matchNode), fetched when somebody first searches.@graview/core/words: a record read as a person reads it (readableFields,pageSections,isLongText,describeNode,tellApart), what an argument asks for (argShape,describeArg), an argument and a refusal in the record's words (argumentWords,failureWords) andviaSaid.@graview/core/seat: an act's answer as its seat may see it (answerSeenBy), the archive behind the undo horizon as a seat may see it (archivedSeenBy, a host'sHistoryHost.archivedanswer), every place an app has (placesOf,placesFrom) and the order things are made in (beginning). Judging the arrangement (arrangementFindings) is@graview/core/check's. - What a page loads first —
@graview/coreand@graview/core/documenthold only what a page draws with. The checker, the city, the figures and the block resolver are on the subpaths above because a bundler places a whole module in every chunk that can reach it: a hosted page imports both barrels up front, and would otherwise carry them before a face is fetched. - A view's CSS, read as a browser reads it —
@graview/core/css, on no page: the CSS tokenizer and parser, and the sanitizer over them (sanitizeStylesheet,sanitizeStylesheets,sanitizeDeclarations,sanitizeValue) that keeps of a stylesheet only what the open kit allows — the tablesCSS_PROPERTIES,CSS_FUNCTIONS,CSS_AT_RULESand the rest,url(#id)on a paint alone, nothing that fetches — up toOPEN_MAX_STYLESHEETcharacters. It is the framework's one judge of CSS:@graview/guestdraws a worker view's stylesheet through it, and the checker holds a document's own stylesheet for every view (brand.views.css) to it, so what passes is what a page draws. - A place's address —
addressOf(place, { basePath })spells a place fromplacesOfas the routed face links to it under a host's base path,pathWithinreads an address back, andbasePathOfnormalizes a base. Asearchhit says its own: a record, a kind's list or a place carriesaddress, spelled the same way under thebasePathit is given, and a seat finds only the records its sight lets it open. - The screens a device offers —
@graview/core/devices, on no page: the strip a fixed screen draws along its foot (deviceScreensOf: the declaration'sdevices.screens, else the home and the app's jobs, else its bar), the place a screen names (screenPlaceOf), and the checker's words for one it cannot offer (deviceFindings), held toMOST_DEVICE_SCREENSandLONGEST_SCREEN_LABEL.@graview/pages/devicedraws it. - Conformance —
@graview/core/conformance: fixtures a host runs against a version (conformance()) to prove it reads, compiles and derives the same. - A status board's moves —
@graview/core/describe:columnReachsays which acts move a card to which column — the named steps that set the field to that column's value, or else an act told the value — andcolumnMovesthe ones one seat may run on one record, its conditions judged. - What a declaration is made of —
@graview/core/compose, on no page:traitsOf(document | app)reads a declaration's traits in the closed vocabularyTRAITS(people who own things, a status that moves, money against a budget, …), each with the kinds, fields, rules, lenses and acts that carry it and one sentence, never off hand-written tags;startingDocument({ base?, drop?, add?, name, purpose? })composes a document from a template's parts and trait modules, each joined to the kind people see most, that compiles with no warning, and says what it took from where; besideinferJobsandcomposeDesign, which propose a declaration's jobs and one design whole.
npx graview create my-app # a product on Graview, started (also: npm create graview)
npx graview check ./dist/domain/app.js
npx graview docs ./dist/domain/app.jscreate writes the declaration split into domain and UI, a shell, a headless test and a CI workflow, initializes a repository, installs, and says what to do next. --link <path> consumes the framework from a sibling checkout by path instead of a registry — the only way that works until the packages are published — and refuses a framework that is not built. The generator behind it is @graview/core/scaffold, a pure function from a name and a first kind to a list of files, for a host that provisions apps.
What it exports (438)
Read off the package's own barrel, so this is what is there today.
accentProblemactingAsActRefusalactSpelledAsactTitleaddressOfAI_BRIDGE_PATHallLabelappLinkFieldapplySpliceAppTidyingARCHIVEDarchivedFromargumentsTakenarrangedEntriesarticleasBoundToaskedArgumentsaskedFieldsOfassertHeadassertReadableassetSrcattachFrictionAUTHOR_KINDSauthorKindOfbareOpbasePathOfBIND_PERSONbindSchemabindsOfboundPeopleForbrandFromAccentbrokenWordscapabilitiescapabilitiesOfcheckBrandContrastcheckContrastcheckKitContrastcheckpointcheckpointOncheckpointsBetweencheckUndochoiceWordscitedFieldsOfcolorsIncompileMutationcompositeconnectorHueColorconnectorKitForcontrastcountedcoverageUnlinkedWordscreateMemoryAdaptercreateSchemacreateSqlAdaptercreateSqliteAdaptercreateViewRegistryDARKdarkGroundForDATE_VALUEdateOndayAsReaddayOfdayOfMomentdayOfMonthAsReaddaysAsReaddaySpanOfdayZoneForDECISION_BRIDGE_PATHdeclaredLensesdeclareInstallationDEFAULT_KITDEFAULT_LOCALEdefineAppdefineInvariantdefineMutationdefineNodedefOfderiveArchiveMutationsderivedViaderiveEditMutationsderiveMutationsderiveRemoveMutationsdescribeCapabilitydescriptionOfdiffSnapshotsDISPLAY_TRACKINGDOCUMENT_FONTSdocumentSchemesdurationFieldEDGE_FIELDSedgeIdeditMutationNameeditViaeffectivityemojiMarkemojiOfemojiProblememojiSvgEMPTY_DIFFevaluateexcerptextendInvariantsextendMutationsfamiliesInfaviconHrefFIDELITIESFIELD_SIGHTfieldInPassingFieldRevisionsfieldsWrittenfieldsWrittenByfieldWordsfieldWritersfileAtfileFieldfileKindOffilesOffileSrcfoldPresencefontProblemFORMATSformatStampFRAMEWORK_VERSIONFRESH_KEYfreshAddressGraphGRAPH_FINDING_CODESGraphErrorGRAVIEW_COLORSGRAVIEW_FACEgraviewSymbolGridSortgridSortOfgridSortProblemgroundProblemgroundReadsgroundSchemesheadOfhidesFromholdsValueHOME_SLUGHOST_ASSETShueForhumanizeFieldhumanizeValueimageFieldinAskedOrderINSTALLATION_MODULEInvalidArgumentsinverseOfinvertinvertedisAppAddressisAppLinkFieldisArchivedisAutomatedisCurrentisEffectiveBetweenisEffectiveOnisEmptyDiffisFileValueisFocusisImageisInlineSvgisLeftAloneisLinkedTargetisMadeRefisoDateisoShadeisoTodayisRepeatisRepeatFieldisShippedLensisSystemisSystemFamilyisUnsetisVideoisVisitorAuthorisWithheldKEEP_LINKKeepsSeatkeptSubscriptionkindPathkitVariableslabelOflayerlayerPropertyLAYERSlayerVariablesLIGHTLineageLINEAGE_BASIS_LIMITLINEAGE_EVIDENCE_LIMITLINEAGE_LIMITLINEAGE_MODEL_LIMITlineageOflinkedReadslinkedRecordFieldlinkedRefOflinkedRefsOflinkedRelationOflinkedRelationslinkedValueLOCAL_BRIDGE_PATHLOCAL_LAYERSlocaleForLogHeadMovedErrorLOGO_RULESlogoForlogoOflogoSchemelogSeenByluminancemademarkCitesmarkCollaborativemarkdownFieldmarkHrefmarkProblemMAX_INLINE_SVGmeInmemorySubscriptionsmemoryViewsmeOfmintPersonIdminutesAsReadMissingRecordErrorMODULES_AUTHORmomentAsReadmomentAtAGlancemonthAsReadMOST_STANDINGmotionnamedAuthorsnameInPassingnameKeynameOfAuthornamesUnseennearestActNEVER_WRITTENNewerFormatErrornextExpirynextOccurrenceNO_KEPT_VIEWSnodeRefnodeRefArgsnodeRefKindsnormalizenounOfnumberAsReadnumbersSpelledoccurrencesofferedPlacesONE_FACE_LAYERSonePerPictureonPublishopeningOfOperationLogorderKindsOVERVIEW_PATHOVERVIEW_SLUGpagesTitleparseLinkedTargetparseParticipantPARTIAL_DAYparticipantKeypassingShadePastErrorpathWithinPermissionDeniedErrorpermitspermittedMutationsPERSON_SEATphoneFieldplaceFieldplaceLabelplacePathplaceSlugplaceTidyingPLAIN_WEIGHTSpluralLabelpluralOfPRESENCE_TTL_MSpresenceNamepresenceStandsPREVIEW_BATCHprimaryOfPRIMITIVE_OPSproblemsMovedprofileOfPROPOSE_CHANGESProposeChangesArgsproposesproviderCanPUBLISHPublishingreaderSettingsreadLinkedThroughreadsPublishedReceiveErrorrecordFrictionrecordPathrecordsOfredactREFUSAL_REASONSrefusalOfREMOTE_PRESENCE_TTL_MSREMOVED_VIEW_DAYSremovedLensNameremoveMutationNameremoveViarepairPlanrepeatedByrepeatFieldrepeatKeyrequiredRolesOfresolveKitresolveModulesrolesOfrolesWhoCouldRuleBudgetErrorsafeFileHrefsamePicturesamePresencesayInsayingInSCENE_LAYERSsceneTitleSchemaErrorSCHEMESSEARCH_UNASKEDseatLensSeatLensseatMarkseatPersonOfseatsKeptseenBySeenOptionsseesseesIdservesReaderssettableFieldssha256HexSHAPEshapedRulesshapeOfsharesItsNameSHIPPED_LENS_NAMESSHIPPED_LENSESsightedKindssightMayKeepSignInsignInInsteadsnapshotHashsortForGridspellingOfsqlFromDatabaseSQLITE_TABLE_SHAPEstackOfStoreSTUDIO_DOOR_PATHsubjectKindsOfsubscriberOfsubscriptionIdsuggestionsMayWaitSuggestionVotesummarizesupportingKindssvgProblemsymbolCutSYSTEM_FONTSSYSTEM_STACKStakesAnIdtellTheWatchOfAPressRefusedByItsInputtellTheWatchWhatIsUnseenTEXT_PAIRStextSizetickEachDayTIME_OF_DAYtimeAsReadtimeFieldtimeZoneFortimeZoneProblemtouchedBytouchesUnseenTrackedReadertransformCaretTYPE_TEXTTYPOGRAPHYtypographyOfUndoBlockedErrorundoPrimitivesUnknownMutationErrorunknownPrimitiveUnregisteredInvariantErrorunseatedunseatedOpunseatedSnapshotUNSETuntilTheDayTurnsunwrittenFieldsupgradeOpupgradeSnapshotvalidateGraphvalidRepeatVALUE_TYPESvideoFieldvideoWordsviewReferenceviolationKeyviolationsTouchingVISITOR_PRESENCE_TTL_MSVoteVOTE_SUGGESTIONVotesOptionswalkKindsweekdayAsReadweekdayNameWEEKDAYSWEIGHTSwhenAsReadwhyNotWIRE_PROTOCOLwithArticleWITHHELD_AUTHORWITHHELD_INTENTwithholdwithInversewithMemoryRevisionswithValidProfilewouldRunWriterswritersOfwritesOfwrittenByzzoneFor