@hypit/hypit 0.0.1 → 0.1.0

package/packages/temporal/src/types.ts

@@ -0,0 +1,124 @@
+export type FramePoint = {
+  readonly frame: number;
+};
+
+export type LocatedSelection = {
+  readonly id: string;
+  readonly start: FramePoint;
+  readonly end: FramePoint;
+};
+
+export type LocatedMoment = {
+  readonly id: string;
+  readonly cue: FramePoint;
+};
+
+export type LocatedProgram = {
+  readonly id: "program";
+  readonly start: FramePoint;
+  readonly end: FramePoint;
+};
+
+export type LocatedSegment = {
+  readonly id: string;
+  readonly start: FramePoint;
+  readonly end: FramePoint;
+};
+
+/** Exact author duration. Decimal source spelling is reduced before reaching this value. */
+export type TemporalDuration =
+  | { readonly unit: "frames"; readonly value: number }
+  | { readonly unit: "milliseconds"; readonly value: number }
+  | { readonly unit: "seconds"; readonly numerator: number; readonly denominator: number };
+
+/** A single projected boundary before it is resolved into ProgramSpace. */
+export type TemporalInstantExpression =
+  | { readonly ref: "program.start"; readonly offset?: TemporalDuration }
+  | { readonly ref: "program.end"; readonly offset?: TemporalDuration }
+  | { readonly ref: "selection.start"; readonly offset?: TemporalDuration }
+  | { readonly ref: "selection.end"; readonly offset?: TemporalDuration }
+  | { readonly ref: "segment.start"; readonly offset?: TemporalDuration }
+  | { readonly ref: "segment.end"; readonly offset?: TemporalDuration }
+  | { readonly ref: "moment.cue"; readonly offset?: TemporalDuration }
+  | { readonly ref: "absolute"; readonly at: TemporalDuration; readonly offset?: TemporalDuration };
+
+/** Runtime dependency used to resolve an Instant. This is not its authoring authority. */
+export type TemporalSource = {
+  readonly spaceId: string;
+  /** Present when the boundary originates in a Script. */
+  readonly narrativeId?: string;
+  readonly kind: "program" | "selection" | "segment" | "moment";
+  readonly id: string;
+};
+
+/**
+ * The author-owned inverse of one projected Instant. Runtime dependencies and
+ * author authority are deliberately separate: an expression may read an
+ * anchor while remaining writable only at its author parameter.
+ */
+export type TemporalInstantAuthority =
+  | { readonly kind: "semantic"; readonly boundary: "start" | "end" | "cue" }
+  | {
+      readonly kind: "parameter";
+      readonly binding: string;
+      readonly relation: "direct" | "after-start" | "before-end";
+    }
+  | { readonly kind: "fixed" };
+
+/** Input value for an Instant projection producer. */
+export type TemporalInstantSpec = {
+  readonly id: string;
+  /** Author/domain entity whose timing this projection controls. */
+  readonly subjectId: string;
+  readonly projection: TemporalInstantExpression;
+  readonly authority: TemporalInstantAuthority;
+};
+
+/** Input value for composing two resolved Instants into a Window. */
+export type TemporalWindowSpec = {
+  readonly id: string;
+  /** Author/domain entity whose timing this projection controls. */
+  readonly subjectId: string;
+};
+
+export type FrameSpan = {
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};
+
+export type ProjectedInstant = {
+  readonly id: string;
+  readonly subjectId: string;
+  readonly source: TemporalSource;
+  readonly projection: TemporalInstantExpression;
+  readonly authority: TemporalInstantAuthority;
+  readonly frame: number;
+};
+
+export type ProjectedWindow = {
+  readonly id: string;
+  readonly subjectId: string;
+  readonly start: ProjectedInstant;
+  readonly end: ProjectedInstant;
+  readonly span: FrameSpan;
+};
+
+/** Public projection protocol consumed by domain programs. */
+export type TemporalInstant = ProjectedInstant;
+
+/** Public projection protocol composed from two independently traced Instants. */
+export type TemporalWindow = ProjectedWindow;
+
+export type WindowRelation = "independent" | "disjoint";
+
+export type TriggerPoint = {
+  readonly id: string;
+  readonly frame: number;
+};
+
+export type TriggeredSchedule = {
+  readonly outer: FrameSpan;
+  readonly terminalFrame: number;
+  readonly cumulative: readonly FrameSpan[];
+  readonly exclusive: readonly FrameSpan[];
+};

package/packages/temporal-markup/README.md

@@ -0,0 +1,75 @@
+# `@hypit/temporal-markup`
+
+Shared SVML author-time projection helpers for `@hypit/temporal`. The Surface lowers authored
+Selection, Segment, Moment or explicit clock expressions to ordinary Instant projections and Window
+composition. A domain consumer receives the projected values and explicit ProgramSpace; it does not
+locate Script words or infer a semantic source inside its renderer.
+
+The package exports `createTemporalWindowProjection`, `createTemporalInstantProjection`,
+`resolveTemporalContext`, `createTemporalSpace`, attribute vocabulary, and the exact duration/instant parsers. These are helpers for component
+Surfaces, not standalone author tags or a new Track.
+
+## Time context
+
+A Track Surface can accept `semantic={speech.semantic}` or `space={animation}`. Resolve that choice
+with `resolveTemporalContext({ element, resolveReference })`, and pass the result to
+`createTemporalSpace({ id, element, ...context })`. Preserve its component and fragment drafts.
+Supply `...context, space: time.space` to each temporal projection helper, and pass `time.space.ref`
+to the domain Fragment. Its input Type is `programSpaceTypes.programSpace`.
+
+A semantic context locates Script references and supplies the performance's time axis. A declared
+space supplies a clock for authored animation. Literal times and program boundaries work in either
+context. A Script reference needs `semantic` to locate it; the renderer never invents that mapping.
+
+## Window forms
+
+A Surface using the shared Window vocabulary accepts one complete form:
+
+| Authored attributes | Meaning |
+| --- | --- |
+| `during="program"` | The complete program Window. |
+| `during={story.segment.opening}` | A Segment's Window. |
+| `during={story.selection.proof}` | A Selection's Window, including its authored endpoint affinity. |
+| `at="2s" for="8f"` | Start two seconds into the program and last eight frames. |
+| `at={story.moment.reveal} for="8f"` | Start at a Moment and last eight program frames. |
+| `until={story.moment.reveal} for="250ms"` | End at a Moment after a span of 250 milliseconds. |
+| `start="program.start" end="moment.cue" moment={story.moment.reveal}` | Compose independently authored endpoints. |
+
+Do not combine forms: `during="program" until={...}` is not shorthand for a shortened program.
+Use explicit `start` and `end` for that relationship. Expressions can reference `program.start`,
+`program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end` or `moment.cue`.
+Bind the corresponding `selection`, `segment` or `moment` reference attribute when an expression
+uses it. An endpoint may also be an absolute duration from program start, such as `1.5s`.
+
+Offsets use an explicit sign and duration, for example `selection.start - 2f`. Frames and milliseconds
+are integers (`8f`, `250ms`); seconds may be fractional (`1.5s`). Projection preserves the expression
+and its authority. Invalid or out-of-program results are errors rather than silently clipped time.
+
+## Instant forms
+
+An Instant consumer has a different job: an event or activation with one temporal point.
+
+| Authored attributes | Meaning |
+| --- | --- |
+| `at={story.moment.reveal}` | The authored Moment. |
+| `at={story.selection.proof} boundary="start"` | An explicitly chosen Selection boundary. |
+| `at={story.segment.opening} boundary="end"` | An explicitly chosen Segment boundary. |
+| `at="2.6s"` | An authored event 2.6 seconds from program start. |
+| `instant="program.start + 8f"` | A projected clock expression. |
+
+The domain component decides what happens after that point. An answer may remain visible, a Sequence
+may replace its member, or a motion may run according to its own authored schedule. Instant projection
+does not impose the event's visible duration. A component whose public role requires a Script Moment
+can deliberately admit only that form; consumers need not expose unrelated temporal options.
+
+## Component boundary
+
+The Surface supplies an author-facing `subjectId` for the actual item whose time is being projected,
+separately from graph-qualified operation ids. The graph wires the resulting Instant or Window and
+ProgramSpace into the consumer. Keep projection outside the domain Producer: it consumes resolved
+time and implements its own schedule or state, while the shared temporal protocol retains where that
+time came from. An outer lifetime and child activations are separate inputs when a component persists
+between events.
+
+Script's `@`, `~@`, close markers and Moment syntax belong to `@hypit/script`; media playback belongs
+to `@hypit/media-track`; a graphic component's reveal or preset semantics belong to that component.

package/packages/temporal-markup/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@hypit/temporal-markup",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/program-space": "workspace:*"
+  }
+}