@hypit/hypit 0.0.1 → 0.1.0

package/packages/interview-emoji-reveal/src/surface.ts

@@ -0,0 +1,110 @@
+import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import {
+  assertAttributes, assertEmptyElement, optionalTextAttribute, textAttribute, type MarkupAttributeValue, type StructuredSurfaceHandler,
+  type SurfaceComponentDraft, type SurfaceRecordDraft, type SurfaceResolvedReference,
+} from "@hypit/markup";
+import { artifactTypes } from "@hypit/artifact";
+import { narrativeTypes } from "@hypit/narrative";
+import { sameType, type CanonicalValue, type TypeRef } from "@hypit/protocol";
+import { spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import type { SvsRecipe } from "@hypit/svs";
+import { createTemporalInstantProjection, createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+
+import { createEmojiRevealFragment } from "./fragment.js";
+import { emojiRevealTypes } from "./manifest.js";
+import { sealEmojiRevealHeader, sealEmojiRevealItemSpec } from "./program.js";
+import { decodeEmojiRevealStyle } from "./style.js";
+
+function reference(raw: MarkupAttributeValue | undefined, label: string, expected: TypeRef, resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+  const value = resolve(raw.path); if (value === undefined || !sameType(value.type, expected)) throw new Error(`${label} has the wrong Type.`);
+  return value;
+}
+function oneOfReference(raw: MarkupAttributeValue | undefined, label: string, expected: readonly TypeRef[], resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+  const value = resolve(raw.path); if (value === undefined || !expected.some((type) => sameType(value.type, type))) throw new Error(`${label} has the wrong Type.`);
+  return value;
+}
+function inline<T>(value: SurfaceResolvedReference, label: string): T {
+  if (value.record?.value.kind !== "inline") throw new Error(`${label} must resolve during author compilation.`);
+  return value.record.value.value as unknown as T;
+}
+
+function boolean(element: Parameters<StructuredSurfaceHandler>[0]["element"], name: string, fallback: boolean): boolean {
+  const source = optionalTextAttribute(element, name);
+  if (source === undefined) return fallback;
+  if (source === "true") return true;
+  if (source === "false") return false;
+  throw new Error(`${element.name}.${name} must be true or false.`);
+}
+
+export const decodeEmojiRevealStyleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id", "recipe"]); assertEmptyElement(element);
+  const id = textAttribute(element, "id");
+  const recipe = reference(element.attributes.recipe, `${element.name}.recipe`, svsRecipeType, resolveReference);
+  const style = decodeEmojiRevealStyle(id, inline<SvsRecipe>(recipe, `${element.name}.recipe`));
+  return { records: [{ id, type: emojiRevealTypes.style, value: { kind: "inline", value: style as unknown as CanonicalValue }, range: element.range }], components: [], fragments: [] };
+};
+
+export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id", "semantic", "space", "canvas", "style", "placeholder", ...temporalWindowAttributeNames]);
+  const id = textAttribute(element, "id");
+  const context = resolveTemporalContext({ element, resolveReference });
+  const time = createTemporalSpace({ id: id, element, ...context });
+  const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
+  const style = reference(element.attributes.style, `${element.name}.style`, emojiRevealTypes.style, resolveReference);
+  const placeholder = reference(element.attributes.placeholder, `${element.name}.placeholder`, artifactTypes.blob, resolveReference);
+  const outer = createTemporalWindowProjection({ id, subjectId: id, element, ...context, space: time.space, resolveReference });
+  const headerId = `${id}.header`;
+  const records: SurfaceRecordDraft[] = [...outer.records, {
+    id: headerId, type: emojiRevealTypes.header,
+    value: { kind: "inline", value: sealEmojiRevealHeader({ id }) as unknown as CanonicalValue }, range: element.range,
+  }];
+  const temporalComponents: SurfaceComponentDraft[] = [...time.components, ...outer.components];
+  const temporalFragments = [...time.fragments, ...outer.fragments];
+  const items: { specName: string; iconName: string; activationName?: string }[] = [];
+  const inputs: Record<string, typeof time.space.ref> = {
+    header: { kind: "record", id: headerId }, space: time.space.ref, canvas: canvas.ref, style: style.ref,
+    placeholder: placeholder.ref, outer: outer.ref,
+  };
+  const ids = new Set<string>();
+  let index = 0;
+  for (const child of element.children) {
+    if (child.kind === "text") { if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Item children.`); continue; }
+    if (child.name.split(":").at(-1) !== "Item") throw new Error(`${element.name} accepts only Item children.`);
+    assertAttributes(child, ["id", "icon", "preset", "at"]); assertEmptyElement(child);
+    index += 1;
+    const itemId = textAttribute(child, "id");
+    if (ids.has(itemId)) throw new Error(`${element.name} contains duplicate Item id ${itemId}.`); ids.add(itemId);
+    const preset = boolean(child, "preset", false);
+    const timed = child.attributes.at !== undefined;
+    if (preset && timed) throw new Error(`${child.name} cannot combine preset=true with at.`);
+    if (!preset && !timed) throw new Error(`${child.name} requires at unless preset=true.`);
+    const icon = reference(child.attributes.icon, `${child.name}.icon`, artifactTypes.blob, resolveReference);
+    const spec = sealEmojiRevealItemSpec({ id: itemId, preset });
+    const suffix = String(index).padStart(4, "0");
+    const specId = `${id}.item.${suffix}.spec`; const specName = `item-${suffix}-spec`;
+    const iconName = `item-${suffix}-icon`;
+    records.push({ id: specId, type: emojiRevealTypes.itemSpec, value: { kind: "inline", value: spec as unknown as CanonicalValue }, range: child.range });
+    inputs[specName] = { kind: "record", id: specId }; inputs[iconName] = icon.ref;
+    if (preset) items.push({ specName, iconName });
+    else {
+      const activation = createTemporalInstantProjection({
+        id: `${id}.item.${suffix}.activation`, subjectId: itemId,
+        element: child, ...context, space: time.space, resolveReference, semanticAttribute: "at", projectedAttribute: false,
+      });
+      records.push(...activation.records); temporalComponents.push(...activation.components); temporalFragments.push(...activation.fragments);
+      const activationName = `item-${suffix}-activation`;
+      inputs[activationName] = activation.ref;
+      items.push({ specName, iconName, activationName });
+    }
+  }
+  if (items.length === 0) throw new Error(`${element.name} requires at least one Item.`);
+  const fragment = createEmojiRevealFragment(items);
+  return {
+    records,
+    components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],
+    fragments: [...temporalFragments, fragment], exports: [`${id}.program`, `${id}.track`],
+  };
+};

package/packages/interview-emoji-reveal/src/types.ts

@@ -0,0 +1,52 @@
+import type { BlobRef } from "@hypit/protocol";
+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
+
+export type EmojiRevealHeader = { readonly id: string };
+
+export type EmojiRevealItemSpec =
+  | { readonly id: string; readonly preset: true }
+  | { readonly id: string; readonly preset: false };
+
+export type EmojiRevealStyle = {
+  readonly id: string;
+  readonly centerX: number;
+  readonly topY: number;
+  readonly slotSizePx: number;
+  readonly gapPx: number;
+  readonly paddingXPx: number;
+  readonly paddingYPx: number;
+  readonly background: string;
+  readonly borderColor: string;
+  readonly borderWidthPx: number;
+  readonly radiusPx: number;
+  readonly shadowColor: string;
+  readonly shadowXPx: number;
+  readonly shadowYPx: number;
+  readonly shadowBlurPx: number;
+  readonly shadowSpreadPx: number;
+  readonly iconSizePx: number;
+  readonly revealFrames: number;
+  readonly stackingOrder: number;
+};
+
+export type EmojiRevealItem =
+  | {
+      readonly spec: EmojiRevealItemSpec & { readonly preset: true };
+      readonly icon: BlobRef;
+    }
+  | {
+      readonly spec: EmojiRevealItemSpec & { readonly preset: false };
+      readonly icon: BlobRef;
+      readonly activation: TemporalInstant;
+    };
+
+export type EmojiRevealSet = { readonly items: readonly EmojiRevealItem[] };
+
+export type EmojiRevealProgram = {
+  readonly id: string;
+  readonly programSpaceId: string;
+  readonly outer: TemporalWindow;
+  readonly style: EmojiRevealStyle;
+  readonly placeholder: BlobRef;
+  readonly items: readonly EmojiRevealItem[];
+};

package/packages/markup/README.md

@@ -0,0 +1,81 @@
+# `@hypit/markup`
+
+Official XML-like Author Frontend normally used by `.svml` source units. The suffix has no parser
+authority; a mandatory `<?svml using="@hypit/markup@1"?>` Header selects this Frontend. It owns only the `<svml>` envelope,
+the leading Import Prologue, namespace binding, generic structured elements and dispatch to
+package-owned Markup Surface Host facets.
+
+The package has no built-in Script, media or video vocabulary. `<script>` is accepted only when an
+imported package contributes that tag through a locked Markup Host facet. The semantic Module
+Manifest contains no XML or parser fact. The current registry is for trusted official/in-process use; it is not a security
+sandbox for third-party parser code.
+
+```svml
+<?svml using="@hypit/markup@1"?>
+<svml>
+  <import from="@hypit/script@1"/>
+  <import as="recipes" source="./recipes.svs"/>
+
+  <script id="story">
+    <opening><ALICE>Hello.</opening>
+  </script>
+</svml>
+```
+
+## Author syntax
+
+Imports must precede body declarations. `from="@scope/package@1"` selects a logical Module ABI from
+an installed package; `source="./other.svs"` selects another SourceUnit. A Host may also resolve a
+non-relative Source locator such as an explicitly exported package Source; this is the same Markup
+construct and does not give Markup package-manager knowledge. An `as` alias prefixes that module's
+tags or that Source's public bindings. A Source import is not textual inclusion and does not make
+its private graph identifiers public. Aliasing does not rewrite authored Narrative
+identities: separately declaring two Scripts named `story` in one closure is a conflict, even when
+their binding paths use different import aliases.
+
+Attributes are quoted strings or whole-value references such as `source={portrait.image}`. Braces
+contain a binding path, not JavaScript. The receiving Surface owns literal number/boolean parsing,
+expression units, allowed children and output names. There is no universal `.image` or `.track`
+suffix. Generic structured text and quoted attributes decode `&lt;`, `&gt;`, `&amp;`, `&quot;` and
+`&apos;`; a raw Surface such as Script owns its own body grammar and escapes. Comments use
+`<!-- ... -->` outside raw bodies.
+
+Put values before structured Surfaces that resolve them. During decoding, `resolveReference` sees
+imported public values, earlier authored Records and earlier Component output declarations. It can
+inspect an inline Recipe immediately but cannot inspect a generated value that has not run.
+Arbitrary forward references are not a general author-language guarantee. These declaration-order
+requirements are distinct from execution order, which follows graph dependencies and demanded
+Outputs.
+
+## Frontend implementation
+
+Decoding has two passes. `discoverMarkup` reads only the root and complete leading Import Prologue.
+After Driver supplies one immutable resolved closure, `decodeMarkup` freezes the visible Surface
+scope and parses the body. A raw Surface receives the source cursor immediately after its opening
+tag and must return the cursor after its own close; a structured Surface receives Markup's generic
+element tree.
+
+A Surface may contribute three kinds of inert data:
+
+- authored typed Record drafts;
+- parser-independent Author Component drafts;
+- content-addressed Graph Fragments used by those components.
+
+Raw and Structured Surface handlers are asynchronous and receive one narrow `resolveAsset()`
+capability. This is the only way a Surface can turn an author-written asset locator into a
+content-addressed `BlobRef`; Markup never exposes filesystem APIs or a resolved local path. The
+Compiler Host, not the Surface, owns containment, read-once behavior and byte transfer. A handler
+that does not request assets remains unchanged apart from being awaitable.
+
+Markup validates source ranges, duplicate identities, Host-facet-declared Record types and complete
+Fragment references. It strips diagnostic ranges before sealing one `hypit.author-module@1`, so
+source reflow does not change author semantics. It does not expand Fragments while reading the
+body. Surface handlers can resolve references through the scoped decoder context described above;
+after all drafts are collected, `@hypit/elaborator` resolves their graph wiring and emits the Core
+Graph. That later graph pass does not make future authored Records available to an earlier decoder.
+
+Direct `decodeMarkup()` calls require every source import to be supplied as an already resolved
+namespace. The reference `compileSourceClosure()` orchestration in `@hypit/elaborator` recursively
+discovers those SourceUnits. Each dependency's own Source Header selects its exact Frontend; Markup
+never chooses a dependency parser. The compiler decodes dependencies first and then calls Markup
+with their locked public exports. Markup itself never reads a file or guesses a Frontend.

package/packages/markup/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@hypit/markup",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/core": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/host": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/markup/src/element.ts

@@ -0,0 +1,39 @@
+import type { StructuredElement } from "./types.js";
+
+export function assertAttributes(
+  element: StructuredElement,
+  allowed: readonly string[],
+  required: readonly string[] = [],
+): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+  if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}.`);
+  const missing = required.filter((name) => element.attributes[name] === undefined);
+  if (missing.length > 0) throw new Error(`${element.name} requires ${missing.join(", ")}.`);
+}
+
+export function assertExactAttributes(element: StructuredElement, names: readonly string[]): void {
+  assertAttributes(element, names, names);
+}
+
+export function assertEmptyElement(element: StructuredElement): void {
+  if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
+    throw new Error(`${element.name} must be empty.`);
+  }
+}
+
+export function localName(name: string): string {
+  return name.slice(name.lastIndexOf(":") + 1);
+}
+
+export function textAttribute(element: StructuredElement, name: string, fallback?: string): string {
+  const value = element.attributes[name];
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${element.name}.${name} must be text.`);
+  }
+  return value.trim();
+}
+
+export function optionalTextAttribute(element: StructuredElement, name: string): string | undefined {
+  return element.attributes[name] === undefined ? undefined : textAttribute(element, name);
+}

package/packages/markup/src/error.ts

@@ -0,0 +1,20 @@
+export class MarkupFrontendError extends Error {
+  readonly code: string;
+  readonly sourceName: string;
+  readonly offset: number | undefined;
+  readonly line: number | undefined;
+  readonly column: number | undefined;
+
+  constructor(code: string, message: string, sourceName: string, offset?: number, source?: string) {
+    const before = offset === undefined || source === undefined ? undefined : source.slice(0, offset);
+    const line = before === undefined ? undefined : before.split("\n").length;
+    const column = before === undefined ? undefined : [...(before.split("\n").at(-1) ?? "")].length + 1;
+    super(`${code}: ${message}${line === undefined ? "" : ` (${sourceName}:${line}:${column})`}`);
+    this.name = "MarkupFrontendError";
+    this.code = code;
+    this.sourceName = sourceName;
+    this.offset = offset;
+    this.line = line;
+    this.column = column;
+  }
+}