@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/core

Entry 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 — defineNode and createSchema. 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 derived edit-<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 an ActRefusal whose reason and sentence a host can show (refusalOf reads one): refused when the act's own rule says no, invalid for 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 Principal is an Author with 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): a FileValue, its href a path on the host, uploaded through the page's HostFiles and drawn where the host serves it (fileSrc). A video's value may say its poster, its duration in seconds and its captions (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, TYPOGRAPHY and isoShade(scheme), resolved for a brand by shapeOf and typographyOf — 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 by svgProblem and markProblem under the same rules as Graview Cloud's images; faces named from SYSTEM_STACKS, the system's own and DOCUMENT_FONTS, judged by fontProblem; and an accent that does not read as given is refused by accentProblem with 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_FACE and WEIGHTS (Montserrat at 550, 450 and 600, named first in TYPOGRAPHY and never fetched), LOGO_RULES, and the shared-plane symbol as an inline currentColor SVG (graviewSymbol, the micro cut under 28 px by symbolCut). 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), and compileDocument, a document compiled and checked.
  • Documents — @graview/core/document: a whole app as one JSON object, compiled by compileDocumentWithoutCheck into the same app defineApp declares and never run as code (compileDocument from @graview/core/check also asks the checker); toDocument writes 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's connects links from whichever end of the relation its subject is, replaces severs 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, diffDocuments and planMigration change a document and say what the change does to stored data. A host that compiles a document on its server hands the page serializeCompiled(compiled), and the page builds the same app with appFrom or appFromOrCompile from @graview/core/compiled, which carries no compiler (the format is graview-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/typed is the same document in TypeScript: defineDocument returns 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.ts writes a document's kinds, fields (an enum's options as a union) and relations as types, TypesOf<typeof document> derives the same from a defineDocument, and typedReader<Types>(store) reads a store through them (reader.fieldOf(node, "status"), reader.edgesOf(node, "under") and the rest), so a renamed field or relation fails tsc in 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 computed import() 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: SyncEngine over the op log, with a conflict policy (report, theirs, ours), resources the remote owns (readonly, refused here with their because), 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 asks token({ refresh: true }) once when Google refuses an access token; scripts/verify-google-calendar.mjs proves it against a real test calendar (credentials from ~/.graview-google-test.env, made once by scripts/google-calendar-once.mjs; scripts/calendar-sync-demo.mjs is 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 by last_edited_time across 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, and scripts/verify-notion.mjs proves the transport against a real workspace (~/.graview-notion-test.env; --stub against the scripted one). A document declares either as connections.<name> — a calendar, its fields and a color or tag filter, or a database and its properties; read or both, the conflict policy — judged by graview check and run by graview serve and `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 batch via: "import", and says each refused row in words; previewImport keeps nothing, proposeMapping offers a mapping from the header row, and parseCsv reads a CSV or a paste (docs/import.md).
  • The city — @graview/core/scene: sceneThumbnail draws 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; sceneDistricts is 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 than minBuilding pixels (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) and viaSaid. @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's HistoryHost.archived answer), 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/core and @graview/core/document hold 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 tables CSS_PROPERTIES, CSS_FUNCTIONS, CSS_AT_RULES and the rest, url(#id) on a paint alone, nothing that fetches — up to OPEN_MAX_STYLESHEET characters. It is the framework's one judge of CSS: @graview/guest draws 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 from placesOf as the routed face links to it under a host's base path, pathWithin reads an address back, and basePathOf normalizes a base. A search hit says its own: a record, a kind's list or a place carries address, spelled the same way under the basePath it 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's devices.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 to MOST_DEVICE_SCREENS and LONGEST_SCREEN_LABEL. @graview/pages/device draws 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: columnReach says 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 — and columnMoves the 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 vocabulary TRAITS (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; beside inferJobs and composeDesign, 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.js

create 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.

  • accentProblem
  • actingAs
  • ActRefusal
  • actSpelledAs
  • actTitle
  • addressOf
  • AI_BRIDGE_PATH
  • allLabel
  • appLinkField
  • applySplice
  • AppTidying
  • ARCHIVED
  • archivedFrom
  • argumentsTaken
  • arrangedEntries
  • article
  • asBoundTo
  • askedArguments
  • askedFieldsOf
  • assertHead
  • assertReadable
  • assetSrc
  • attachFriction
  • AUTHOR_KINDS
  • authorKindOf
  • bareOp
  • basePathOf
  • BIND_PERSON
  • bindSchema
  • bindsOf
  • boundPeopleFor
  • brandFromAccent
  • brokenWords
  • capabilities
  • capabilitiesOf
  • checkBrandContrast
  • checkContrast
  • checkKitContrast
  • checkpoint
  • checkpointOn
  • checkpointsBetween
  • checkUndo
  • choiceWords
  • citedFieldsOf
  • colorsIn
  • compileMutation
  • composite
  • connectorHueColor
  • connectorKitFor
  • contrast
  • counted
  • coverageUnlinkedWords
  • createMemoryAdapter
  • createSchema
  • createSqlAdapter
  • createSqliteAdapter
  • createViewRegistry
  • DARK
  • darkGroundFor
  • DATE_VALUE
  • dateOn
  • dayAsRead
  • dayOf
  • dayOfMoment
  • dayOfMonthAsRead
  • daysAsRead
  • daySpanOf
  • dayZoneFor
  • DECISION_BRIDGE_PATH
  • declaredLenses
  • declareInstallation
  • DEFAULT_KIT
  • DEFAULT_LOCALE
  • defineApp
  • defineInvariant
  • defineMutation
  • defineNode
  • defOf
  • deriveArchiveMutations
  • derivedVia
  • deriveEditMutations
  • deriveMutations
  • deriveRemoveMutations
  • describeCapability
  • descriptionOf
  • diffSnapshots
  • DISPLAY_TRACKING
  • DOCUMENT_FONTS
  • documentSchemes
  • durationField
  • EDGE_FIELDS
  • edgeId
  • editMutationName
  • editVia
  • effectivity
  • emojiMark
  • emojiOf
  • emojiProblem
  • emojiSvg
  • EMPTY_DIFF
  • evaluate
  • excerpt
  • extendInvariants
  • extendMutations
  • familiesIn
  • faviconHref
  • FIDELITIES
  • FIELD_SIGHT
  • fieldInPassing
  • FieldRevisions
  • fieldsWritten
  • fieldsWrittenBy
  • fieldWords
  • fieldWriters
  • fileAt
  • fileField
  • fileKindOf
  • filesOf
  • fileSrc
  • foldPresence
  • fontProblem
  • FORMATS
  • formatStamp
  • FRAMEWORK_VERSION
  • FRESH_KEY
  • freshAddress
  • Graph
  • GRAPH_FINDING_CODES
  • GraphError
  • GRAVIEW_COLORS
  • GRAVIEW_FACE
  • graviewSymbol
  • GridSort
  • gridSortOf
  • gridSortProblem
  • groundProblem
  • groundReads
  • groundSchemes
  • headOf
  • hidesFrom
  • holdsValue
  • HOME_SLUG
  • HOST_ASSETS
  • hueFor
  • humanizeField
  • humanizeValue
  • imageField
  • inAskedOrder
  • INSTALLATION_MODULE
  • InvalidArguments
  • inverseOf
  • invert
  • inverted
  • isAppAddress
  • isAppLinkField
  • isArchived
  • isAutomated
  • isCurrent
  • isEffectiveBetween
  • isEffectiveOn
  • isEmptyDiff
  • isFileValue
  • isFocus
  • isImage
  • isInlineSvg
  • isLeftAlone
  • isLinkedTarget
  • isMadeRef
  • isoDate
  • isoShade
  • isoToday
  • isRepeat
  • isRepeatField
  • isShippedLens
  • isSystem
  • isSystemFamily
  • isUnset
  • isVideo
  • isVisitorAuthor
  • isWithheld
  • KEEP_LINK
  • KeepsSeat
  • keptSubscription
  • kindPath
  • kitVariables
  • labelOf
  • layer
  • layerProperty
  • LAYERS
  • layerVariables
  • LIGHT
  • Lineage
  • LINEAGE_BASIS_LIMIT
  • LINEAGE_EVIDENCE_LIMIT
  • LINEAGE_LIMIT
  • LINEAGE_MODEL_LIMIT
  • lineageOf
  • linkedReads
  • linkedRecordField
  • linkedRefOf
  • linkedRefsOf
  • linkedRelationOf
  • linkedRelations
  • linkedValue
  • LOCAL_BRIDGE_PATH
  • LOCAL_LAYERS
  • localeFor
  • LogHeadMovedError
  • LOGO_RULES
  • logoFor
  • logoOf
  • logoScheme
  • logSeenBy
  • luminance
  • made
  • markCites
  • markCollaborative
  • markdownField
  • markHref
  • markProblem
  • MAX_INLINE_SVG
  • meIn
  • memorySubscriptions
  • memoryViews
  • meOf
  • mintPersonId
  • minutesAsRead
  • MissingRecordError
  • MODULES_AUTHOR
  • momentAsRead
  • momentAtAGlance
  • monthAsRead
  • MOST_STANDING
  • motion
  • namedAuthors
  • nameInPassing
  • nameKey
  • nameOfAuthor
  • namesUnseen
  • nearestAct
  • NEVER_WRITTEN
  • NewerFormatError
  • nextExpiry
  • nextOccurrence
  • NO_KEPT_VIEWS
  • nodeRef
  • nodeRefArgs
  • nodeRefKinds
  • normalize
  • nounOf
  • numberAsRead
  • numbersSpelled
  • occurrences
  • offeredPlaces
  • ONE_FACE_LAYERS
  • onePerPicture
  • onPublish
  • openingOf
  • OperationLog
  • orderKinds
  • OVERVIEW_PATH
  • OVERVIEW_SLUG
  • pagesTitle
  • parseLinkedTarget
  • parseParticipant
  • PARTIAL_DAY
  • participantKey
  • passingShade
  • PastError
  • pathWithin
  • PermissionDeniedError
  • permits
  • permittedMutations
  • PERSON_SEAT
  • phoneField
  • placeField
  • placeLabel
  • placePath
  • placeSlug
  • placeTidying
  • PLAIN_WEIGHTS
  • pluralLabel
  • pluralOf
  • PRESENCE_TTL_MS
  • presenceName
  • presenceStands
  • PREVIEW_BATCH
  • primaryOf
  • PRIMITIVE_OPS
  • problemsMoved
  • profileOf
  • PROPOSE_CHANGES
  • ProposeChangesArgs
  • proposes
  • providerCan
  • PUBLISH
  • Publishing
  • readerSettings
  • readLinkedThrough
  • readsPublished
  • ReceiveError
  • recordFriction
  • recordPath
  • recordsOf
  • redact
  • REFUSAL_REASONS
  • refusalOf
  • REMOTE_PRESENCE_TTL_MS
  • REMOVED_VIEW_DAYS
  • removedLensName
  • removeMutationName
  • removeVia
  • repairPlan
  • repeatedBy
  • repeatField
  • repeatKey
  • requiredRolesOf
  • resolveKit
  • resolveModules
  • rolesOf
  • rolesWhoCould
  • RuleBudgetError
  • safeFileHref
  • samePicture
  • samePresence
  • sayIn
  • sayingIn
  • SCENE_LAYERS
  • sceneTitle
  • SchemaError
  • SCHEMES
  • SEARCH_UNASKED
  • seatLens
  • SeatLens
  • seatMark
  • seatPersonOf
  • seatsKept
  • seenBy
  • SeenOptions
  • sees
  • seesId
  • servesReaders
  • settableFields
  • sha256Hex
  • SHAPE
  • shapedRules
  • shapeOf
  • sharesItsName
  • SHIPPED_LENS_NAMES
  • SHIPPED_LENSES
  • sightedKinds
  • sightMayKeep
  • SignIn
  • signInInstead
  • snapshotHash
  • sortForGrid
  • spellingOf
  • sqlFromDatabase
  • SQLITE_TABLE_SHAPE
  • stackOf
  • Store
  • STUDIO_DOOR_PATH
  • subjectKindsOf
  • subscriberOf
  • subscriptionId
  • suggestionsMayWait
  • SuggestionVote
  • summarize
  • supportingKinds
  • svgProblem
  • symbolCut
  • SYSTEM_FONTS
  • SYSTEM_STACKS
  • takesAnId
  • tellTheWatchOfAPressRefusedByItsInput
  • tellTheWatchWhatIsUnseen
  • TEXT_PAIRS
  • textSize
  • tickEachDay
  • TIME_OF_DAY
  • timeAsRead
  • timeField
  • timeZoneFor
  • timeZoneProblem
  • touchedBy
  • touchesUnseen
  • TrackedReader
  • transformCaret
  • TYPE_TEXT
  • TYPOGRAPHY
  • typographyOf
  • UndoBlockedError
  • undoPrimitives
  • UnknownMutationError
  • unknownPrimitive
  • UnregisteredInvariantError
  • unseated
  • unseatedOp
  • unseatedSnapshot
  • UNSET
  • untilTheDayTurns
  • unwrittenFields
  • upgradeOp
  • upgradeSnapshot
  • validateGraph
  • validRepeat
  • VALUE_TYPES
  • videoField
  • videoWords
  • viewReference
  • violationKey
  • violationsTouching
  • VISITOR_PRESENCE_TTL_MS
  • Vote
  • VOTE_SUGGESTION
  • VotesOptions
  • walkKinds
  • weekdayAsRead
  • weekdayName
  • WEEKDAYS
  • WEIGHTS
  • whenAsRead
  • whyNot
  • WIRE_PROTOCOL
  • withArticle
  • WITHHELD_AUTHOR
  • WITHHELD_INTENT
  • withhold
  • withInverse
  • withMemoryRevisions
  • withValidProfile
  • wouldRun
  • Writers
  • writersOf
  • writesOf
  • writtenBy
  • z
  • zoneFor