mechanica-shared 2.0.0-alpha.0

package/dist/types/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Core data types shared between the plugin runtime, the editor, and the
+ * (future) render service. This module is intentionally DOM- and
+ * framework-free so the render side can import it cleanly.
+ */
+/** Scope at which a {@link DataEntry} lives. */
+export type DataScope = 'site' | 'folder' | 'page';
+/** Metadata about the current page, exposed via `usePageData`. */
+export interface PageMeta {
+    title?: string;
+    path?: string;
+    meta?: Record<string, unknown>;
+    /**
+     * Set on paginated variants of a page (`/blog/2`, …): which chunk of its
+     * paginated query this URL shows. Page 1 is the base path and carries none.
+     */
+    pagination?: {
+        page: number;
+        pageCount?: number;
+    };
+}
+/**
+ * Editor-facing metadata describing a *block type* — its schema and palette
+ * presentation, not its placed content. Produced by the block compiler from a
+ * `defineBlock(...)` descriptor.
+ */
+export interface Block {
+    id: string;
+    name: string;
+    /** Palette grouping (was `group` in v1). */
+    category?: string;
+    /** Icon key shown in the block palette. */
+    icon?: string;
+    description?: string;
+    /** Sort order within a category. */
+    order?: number;
+    /** Hidden from the palette. */
+    hidden?: boolean;
+    /** Available only in dev, stripped from production output. */
+    devOnly?: boolean;
+    /**
+     * Restrict the block to pages under these folders (folder paths relative to
+     * `pages/`, e.g. `'docs'`; nested folders match by prefix). Omitted = offered
+     * everywhere. Placed blocks always keep rendering — this only filters what
+     * the palette offers.
+     */
+    folders?: string[];
+    /**
+     * Schema version of this block (defaults to 1). Bump it together with a
+     * `migrate` function whenever a saved page's data needs reshaping (renamed
+     * prop, changed type); placed blocks record the version they were written
+     * with and migrate on load.
+     */
+    version?: number;
+    /**
+     * Upgrade a placed block's data from an older schema version. Receives the
+     * stored data and the version it was written with; mutate it in place or
+     * return the replacement. Must handle every `from < version`.
+     */
+    migrate?: (data: Record<string, unknown>, from: number) => Record<string, unknown> | undefined | void;
+    /**
+     * Example prop values used when the block renders outside a page — the
+     * palette hover preview and the `/@mechanica/preview` route (`mechanica shot`).
+     * Merged over schema defaults, so it only needs the props that matter visually.
+     * A `$slots` key fills the block's slots with child blocks (see
+     * `PreviewSlotEntry` in `mechanica`); unfilled slots preview as placeholders.
+     */
+    previewData?: Record<string, unknown>;
+    /** compact-json-schema describing the editable props. */
+    props?: Record<string, unknown>;
+    /** Slot name → slot metadata (currently `true`). */
+    slots?: Record<string, unknown>;
+}
+/** A block placed in a page's content tree. */
+export interface ContentBlock {
+    id: string;
+    blockId: string;
+    data: Record<string, unknown>;
+    /** Schema version the data was written with (absent = 1); see `Block.version`. */
+    v?: number;
+    /** Either a single default-slot list or a map of named-slot lists. */
+    children?: ContentBlock[] | Record<string, ContentBlock[]>;
+}
+/** A shared data entry declared with `defineData`. */
+export interface DataEntry {
+    id: string;
+    title?: string;
+    /** compact-json-schema describing the data shape. */
+    props?: Record<string, unknown>;
+}
+/**
+ * The runtime state serialized onto the page (`window.state`) and read back by
+ * the runtime to hydrate.
+ */
+export interface State {
+    content: ContentBlock[];
+    /** Effective data: site < folder < page merged, with schema defaults filled. */
+    data: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    /**
+     * Scope buckets for the editor, so it can edit each level and tell which
+     * entries a page overrides. Only injected in dev (the runtime renders `data`).
+     */
+    siteData?: Record<string, unknown>;
+    folderData?: Record<string, unknown>;
+    pageData?: Record<string, unknown>;
+    /** The folder this page lives in (null at the root), so the editor can offer folder scope. */
+    folder?: string | null;
+    /** Base URL the page is served under (for routing/link resolution). */
+    baseUrl?: string;
+    /** Current page metadata. */
+    page?: PageMeta;
+}
+/** A link target produced by the `smartLink` field type. */
+export interface PageLink {
+    id: string;
+    url?: string;
+    query?: string;
+    title: string;
+    external?: boolean;
+    openNewTab?: boolean;
+}

package/dist/types/validate-links.d.ts

@@ -0,0 +1,25 @@
+import type { Block } from './types';
+/** A link on a page pointing at an internal path no page is exported for. */
+export interface LinkIssue {
+    /** The page the broken link lives on. */
+    page: string;
+    /** The internal URL with no matching page. */
+    url: string;
+}
+/** Normalize an internal URL for page-path comparison (drop query/hash/trailing slash). */
+export declare function normalizeInternalUrl(url: string): string;
+/**
+ * Collect the internal link targets on a page: every `smartLink`-formatted
+ * field whose URL is site-relative (starts with `/`) and not marked external.
+ */
+export declare function collectInternalLinks(content: unknown[], blocksMap: Map<string, Block>): string[];
+/**
+ * Cross-check every page's internal `smartLink` targets against the set of
+ * page paths that actually exist. Returns the dead links (empty = all good).
+ * Meant for export/deploy time — a warning, not a hard failure, since a target
+ * may be intentionally served by something else (redirects, external hosting).
+ */
+export declare function validateLinks(pages: Array<{
+    path: string;
+    content?: unknown[];
+}>, blocksMap: Map<string, Block>): LinkIssue[];

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mechanica-shared",
+  "version": "2.0.0-alpha.0",
+  "description": "DOM-free types, schema helpers and page-generation core shared across Mechanica",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.letary.ru/den59k/mechanica.git"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./page-format": {
+      "types": "./dist/types/page-format.d.ts",
+      "bun": "./src/page-format.ts",
+      "import": "./dist/page-format.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "compact-json-schema": "^0.1.5",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  }
+}

package/src/fields.ts

@@ -0,0 +1,106 @@
+import { registerAlias, type SchemaItem } from 'compact-json-schema'
+
+// Mechanica uses compact-json-schema's `format` keyword for its field aliases
+// (`image`, `smartLink`, …). The library keeps `SchemaAnnotations` minimal
+// (`default` only), so declare `format` here — that's what lets the schemas
+// below (and any block/data schema) carry `format` without an `as SchemaItem`
+// cast. The output types for the alias shorthands live in mechanica's
+// `core/field-types.ts` (SchemaTypesMap).
+declare module 'compact-json-schema' {
+  interface SchemaAnnotations {
+    format?: string
+  }
+}
+
+/**
+ * A built-in or user-defined editable field type. The *runtime* half lives here
+ * (the compact-json-schema alias + a default value); the editor component half
+ * is attached separately in the plugin via `defineFieldType`.
+ */
+export interface FieldType {
+  /** Format name, e.g. `'image'`. Used as the compact-json-schema alias. */
+  name: string
+  /** The compact-json-schema definition this alias expands to. */
+  schema: SchemaItem
+  /** Default value, or a factory returning a fresh one. */
+  default?: unknown | (() => unknown)
+}
+
+/** The field types registered by default. */
+export const builtinFields: FieldType[] = [
+  {
+    name: 'image',
+    schema: { type: 'object', format: 'image', properties: { src: 'string', previewSrc: 'string?' } },
+    // Start empty so the editor shows its upload/pick affordance rather than a
+    // placeholder image (and pages render nothing until an image is chosen).
+    default: () => ({ src: '' }),
+  },
+  {
+    name: 'file',
+    schema: { type: 'object', format: 'file', properties: { src: 'string' } },
+    default: () => ({ src: '' }),
+  },
+  {
+    name: 'text',
+    schema: { type: 'string', format: 'text' },
+  },
+  {
+    name: 'color',
+    schema: { type: 'string', format: 'color' },
+  },
+  {
+    name: 'smartLink',
+    schema: {
+      type: 'object',
+      format: 'smartLink',
+      properties: { url: 'string', title: 'string', external: 'boolean', openNewTab: 'boolean' },
+    },
+  },
+  {
+    name: 'multiselect',
+    schema: { type: 'array', format: 'multiselect', items: 'string' },
+  },
+  {
+    name: 'richText',
+    schema: {
+      type: 'array',
+      format: 'richText',
+      items: { type: 'object', properties: { text: 'string', type: 'string?', styles: 'object?' } },
+    },
+    default: () => [{ text: '' }],
+  },
+]
+
+export type RegisterAlias = typeof registerAlias
+
+const fieldDefaults = new Map<string, unknown | (() => unknown)>()
+let registered = false
+
+/**
+ * Register field types as compact-json-schema aliases and record their default
+ * values. Call once per runtime before unfolding any block/data schema.
+ *
+ * @param register Override the alias registrar (defaults to compact-json-schema's).
+ * @param fields   Field set to register (defaults to {@link builtinFields}).
+ */
+export function registerFieldSchemas(
+  register: RegisterAlias = registerAlias,
+  fields: FieldType[] = builtinFields,
+): void {
+  for (const field of fields) {
+    register(field.name as never, field.schema as never)
+    if (field.default !== undefined) fieldDefaults.set(field.name, field.default)
+  }
+  registered = true
+}
+
+/** Resolve the default value for a registered field format, or `undefined`. */
+export function getFieldDefault(format: string): unknown {
+  const value = fieldDefaults.get(format)
+  return typeof value === 'function' ? (value as () => unknown)() : value
+}
+
+/** Whether {@link registerFieldSchemas} has run in this runtime. */
+export function areFieldSchemasRegistered(): boolean {
+  return registered
+}

package/src/generate-page.ts

@@ -0,0 +1,175 @@
+import type { Block } from './types'
+import { passDefaultValue, walkTree, walkSchema, getValueByPath } from './schema'
+
+const HTML_ESCAPES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }
+
+/** Escape a templated value so it's safe in element text and attribute values. */
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"]/g, (char) => HTML_ESCAPES[char]!)
+}
+
+/**
+ * Substitute `{{ a.b }}` placeholders in an HTML string with data values. Used to
+ * template the `<head>` (title, meta, Open Graph, …) from `defineData` values and
+ * the current page. Resolved values are HTML-escaped.
+ */
+export function passDataToHTML(html: string, data: any): string {
+  return html.replace(/\{\{(.+?)\}\}/g, (_match, expr) =>
+    escapeHtml(String(getValueByPath(data, expr.trim()) ?? '')),
+  )
+}
+
+export interface PageState {
+  content: any[]
+  data: Record<string, any>
+  page?: {
+    title?: string
+    path?: string
+    meta?: Record<string, unknown>
+    /** Set on paginated variants: which chunk of the page's paginated query this is. */
+    pagination?: { page: number; pageCount?: number }
+  }
+}
+
+/** What `render` may return: bare HTML, or HTML plus the queries it resolved. */
+export type RenderResult = string | { html: string; query?: Record<string, unknown> }
+
+export interface GeneratePageOptions {
+  /** The index.html template. */
+  index: string
+  /** Block metadata keyed by blockId. */
+  blocksMap: Map<string, Block>
+  /** The page to render. */
+  state: PageState
+  /** Declared data entries (with unfolded schemas) for default-filling. */
+  dataEntries: { id: string; props: any }[]
+  /** Site-level data merged under page data. */
+  projectData?: Record<string, any>
+  baseUrl?: string
+  path?: string
+  /** Rewrite `/assets/` to this base when set. */
+  assetsUrl?: string
+  /**
+   * Extra `<link>` tags for this page's content, injected before `</head>` —
+   * used by the export to preload the block chunks/CSS the page uses (blocks
+   * are code-split out of the client entry).
+   */
+  pageLinks?: (content: any[]) => string[]
+  /**
+   * Render the page state to HTML (provided by the SSR bundle). May also
+   * return the query results resolved during the render — they're baked into
+   * `window.state.query` so the client hydrates them synchronously.
+   */
+  render: (state: any, path: string) => Promise<RenderResult> | RenderResult
+}
+
+/** Render a single page into the index template with serialized state. */
+export async function generatePage(
+  options: GeneratePageOptions,
+): Promise<{ html: string; query: Record<string, unknown> }> {
+  // Fill block-data defaults from each block's schema.
+  walkTree(options.state.content, (block: any) => {
+    const meta = options.blocksMap.get(block.blockId)
+    if (meta) passDefaultValue(block.data, meta.props)
+  })
+
+  // Merge and default the shared data entries.
+  const merged = { ...options.projectData, ...options.state.data }
+  const data = Object.fromEntries(
+    options.dataEntries.map((entry) => [entry.id, passDefaultValue(merged[entry.id] ?? {}, entry.props)]),
+  )
+
+  const state: Record<string, unknown> = {
+    content: options.state.content,
+    data,
+    baseUrl: options.baseUrl,
+    // The page's own path rides along (pagination pathFor, `{{ page.path }}`).
+    page: { path: options.path, ...options.state.page },
+  }
+
+  const result = await options.render(state, options.path ?? '')
+  const rendered = typeof result === 'string' ? result : result.html
+  const query = (typeof result === 'string' ? undefined : result.query) ?? {}
+  // Bake resolved queries into the hydration state — the client reads them
+  // synchronously, so hydration matches the server markup with no refetch.
+  if (Object.keys(query).length) state.query = query
+
+  // Template against data plus the page meta, so `{{ page.meta.title }}` works.
+  let index = passDataToHTML(options.index, { ...data, page: options.state.page })
+
+  // Inject the rendered markup into the #app container. A template without it
+  // would export empty pages — fail loudly instead of silently shipping shells.
+  const appMatch = index.match(/(<div[^>]*\bid="app"[^>]*>)([\s\S]*?)<\/div>/)
+  if (!appMatch) {
+    throw new Error(
+      'index.html has no <div id="app"> container — the rendered page has nowhere to go. ' +
+        'Add <div id="app"></div> to the template body.',
+    )
+  }
+  const start = appMatch.index! + appMatch[1]!.length
+  const end = appMatch.index! + appMatch[0].length - '</div>'.length
+  index = index.slice(0, start) + rendered + index.slice(end)
+
+  const links = options.pageLinks?.(options.state.content) ?? []
+  if (links.length) index = index.replace('</head>', `${links.join('\n')}\n</head>`)
+
+  if (options.assetsUrl) index = index.replace(/\/assets\//g, options.assetsUrl)
+
+  const stateScript = `<script>window.state=${serializeState(state)}</script>`
+  return { html: index.replace('</body>', `${stateScript}\n</body>`), query }
+}
+
+// Characters that can break out of an inline <script>: `<` (closes the tag via
+// `</script>`, or opens `<script`/`<!--`) and the line separators U+2028 / U+2029
+// (invalid in JS string literals). Built from char codes so the source stays
+// plain ASCII.
+const UNSAFE_IN_SCRIPT = new RegExp(`[${[0x3c, 0x2028, 0x2029].map((c) => '\\u' + c.toString(16).padStart(4, '0')).join('')}]`, 'g')
+
+/**
+ * Serialize runtime state for embedding in an inline `<script>`. Plain JSON is
+ * unsafe (a `</script>` in the data would close the tag early), so the few
+ * dangerous characters are escaped to their `\uXXXX` form — valid JSON/JS that
+ * `window.state` and the router's regex read back unchanged.
+ */
+export function serializeState(state: unknown): string {
+  return JSON.stringify(state).replace(UNSAFE_IN_SCRIPT, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'))
+}
+
+export interface GenerateProjectOptions extends Omit<GeneratePageOptions, 'state' | 'path'> {
+  pages: Array<{ content: any[]; data: Record<string, any>; path: string; page?: PageState['page'] }>
+  /** Map an asset path to its emitted path (and copy it). */
+  onFile?: (path: string) => string
+}
+
+/** Render every page of a project, yielding the html, path and resolved queries. */
+export async function* generateProject(
+  options: GenerateProjectOptions,
+): AsyncGenerator<{ html: string; path: string; query: Record<string, unknown> }> {
+  for (const page of options.pages) {
+    page.content = page.content ?? []
+    if (options.onFile) collectFiles(page.content, options.blocksMap, options.onFile)
+    const { html, query } = await generatePage({ ...options, state: page, path: page.path })
+    yield { html, path: page.path, query }
+  }
+}
+
+/** Rewrite asset references (image/file/richText) through `onFile`. */
+function collectFiles(content: any[], blocksMap: Map<string, Block>, onFile: (path: string) => string): void {
+  walkTree(content, (block) => {
+    const meta = blocksMap.get(block.blockId)
+    if (!meta) return
+    walkSchema(block.data, meta.props, (value: any, schema: any) => {
+      if (!value) return
+      if (schema.format === 'image' || schema.format === 'file') {
+        if (value.src) value.src = onFile(value.src)
+        if (value.previewSrc) value.previewSrc = onFile(value.previewSrc)
+      }
+      if (schema.format === 'richText' && schema.type === 'array') {
+        for (const row of value) {
+          if (row.image?.src) row.image.src = onFile(row.image.src)
+          if (row.image?.previewSrc) row.image.previewSrc = onFile(row.image.previewSrc)
+        }
+      }
+    })
+  })
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+export type {
+  Block,
+  ContentBlock,
+  DataEntry,
+  DataScope,
+  PageMeta,
+  State,
+  PageLink,
+} from './types'
+
+export {
+  type FieldType,
+  type RegisterAlias,
+  builtinFields,
+  registerFieldSchemas,
+  getFieldDefault,
+  areFieldSchemasRegistered,
+} from './fields'
+
+export {
+  getDefaultValue,
+  passDefaultValue,
+  buildPreviewData,
+  mergePreviewData,
+  walkTree,
+  walkSchema,
+  getValueByPath,
+} from './schema'
+
+export {
+  generatePage,
+  generateProject,
+  passDataToHTML,
+  serializeState,
+  type GeneratePageOptions,
+  type GenerateProjectOptions,
+  type PageState,
+  type RenderResult,
+} from './generate-page'
+
+export {
+  validateLinks,
+  collectInternalLinks,
+  normalizeInternalUrl,
+  type LinkIssue,
+} from './validate-links'
+
+export { migrateContent, findUnknownBlocks } from './migrate'
+
+// The `.page.md` codec is deliberately NOT re-exported here: it pulls in the
+// YAML parser, and this barrel is imported by the client runtime — nothing in
+// a production page needs to parse pages. Server-side callers (dev store,
+// CLI, rich-text codec) import from 'mechanica-shared/page-format'.
+
+export {
+  parseQueryKey,
+  isPaginatedQuery,
+  resolvePagesQuery,
+  resolveQueryKey,
+  type QuerySource,
+  type QueryContext,
+  type PageQueryItem,
+  type PagesQueryArgs,
+  type PaginatedPagesResult,
+} from './query-engine'
+

package/src/migrate.ts

@@ -0,0 +1,44 @@
+import type { Block, ContentBlock } from './types'
+import { walkTree } from './schema'
+
+/**
+ * Upgrade placed blocks whose data was written with an older schema version.
+ *
+ * Each placed block records the schema version it was saved with (`v`, absent
+ * = 1). When a block type declares a newer `version`, its `migrate` hook runs
+ * with the stored data and the version it came from, then the block is
+ * stamped with the current version. Runs on load (dev state, export) so pages
+ * never render stale-shaped data; the upgrade persists with the next save.
+ *
+ * Returns whether anything changed.
+ */
+export function migrateContent(content: ContentBlock[], blocksMap: Map<string, Block>): boolean {
+  let changed = false
+  walkTree(content, (block) => {
+    const meta = blocksMap.get(block.blockId)
+    const version = meta?.version
+    if (!version) return
+    const from = block.v ?? 1
+    if (from >= version) return
+    if (meta!.migrate) {
+      const result = meta!.migrate(block.data ?? {}, from)
+      if (result) block.data = result
+    }
+    block.v = version
+    changed = true
+  })
+  return changed
+}
+
+/**
+ * Block ids referenced by the content tree that the block registry doesn't
+ * know (deleted or renamed block types). These render as nothing — callers
+ * should surface them (export warning, editor badge).
+ */
+export function findUnknownBlocks(content: ContentBlock[], blocksMap: Map<string, Block>): string[] {
+  const unknown = new Set<string>()
+  walkTree(content, (block) => {
+    if (!blocksMap.has(block.blockId)) unknown.add(block.blockId)
+  })
+  return [...unknown]
+}