Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat: decouple ranking column placement and reveal timing

kashorind0662b0131f6
diff --git a/packages/hyperframes/test/browser-visual.test.ts b/packages/hyperframes/test/browser-visual.test.ts
index 63e189fd..f2ce7b60 100644
--- a/packages/hyperframes/test/browser-visual.test.ts
+++ b/packages/hyperframes/test/browser-visual.test.ts
@@ -1669,6 +1669,7 @@ test("all three Ranking components paint frame-pure progressive states under par
const columnHeader = rankingTrack.sealRankingHeader({ id: "browser-column", variant: "column" });
const columnSpecs = ["one", "two", "three"].map((id, index) => ({
variant: "column" as const, id: `column-${id}`, label: `${index + 1}. ${id}`,
+ rank: index + 1, preset: true,
}));
let columnItems = rankingTrack.createColumnItemSet();
columnSpecs.forEach((spec, index) => { columnItems = rankingTrack.appendColumnItem(columnItems, spec, index === 1 ? icons[index]!.artifact : undefined); });
@@ -1676,9 +1677,21 @@ test("all three Ranking components paint frame-pure progressive states under par
"font-size": 15, "appear-frames": 2, "move-frames": 2, padding: 6, "row-height": 35,
"row-gap": 4, "icon-size": 26, "icon-radius": 5, "stage-size": 46,
}), font).style;
+ let columnSpecSet = rankingTrack.createRankingItemSpecSet(columnHeader);
+ for (const spec of columnSpecs) columnSpecSet = rankingTrack.appendRankingItemSpec(columnSpecSet, spec);
+ const columnSchedule = rankingTrack.buildColumnSchedule({
+ header: columnHeader,
+ items: columnSpecSet,
+ outer: rankingTrack.projectColumnSelectionOuterWindow(map, space, outer),
+ candidates: rankingTrack.createColumnWindowCandidateSet(),
+ });
+ const columnCanvas = sealCanvasSpace({
+ widthPx: width, heightPx: height,
+ origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
+ });
const columnTrack = rankingTrack.renderColumn(space, rankingTrack.buildColumnProgram(
- columnHeader, { xPx: 20, yPx: 180, widthPx: 440, heightPx: 140 },
- schedule(columnHeader, columnSpecs), columnStyle, columnItems,
+ columnHeader, columnCanvas, { xPx: 20, yPx: 180, widthPx: 440, heightPx: 140 },
+ columnSchedule, columnStyle, columnItems,
));
const topHeader = rankingTrack.sealRankingHeader({ id: "browser-top", variant: "top-three" });
diff --git a/packages/ranking/README.md b/packages/ranking/README.md
index 71c46178..4376ea1d 100644
--- a/packages/ranking/README.md
+++ b/packages/ranking/README.md
@@ -6,7 +6,7 @@ Three independent progressive-ranking author components over one private schedul
- `Column`
- `TopThree`
-The package owns variant-specific Programs and Styles. It consumes explicit Selection/Moment,
+The package owns variant-specific Programs and Styles. It consumes explicit Segment/Selection/Moment,
SemanticMap, ProgramSpace, SpatialFrame, font, image and optional sound edges, then lowers to peer
`VisualTrack` and optional `AudioTrack` values. It adds no Ranking field to Core, Composition or
Visual IR.
@@ -26,10 +26,22 @@ copy.
<copy:Value id="winner">No hidden runtime choice</copy:Value>
-<ranking:Column id="priorities" map={timing.map} space={speech.space}
- frame={layout.ranking} during={story.selection.ranking}
- triggers={story.moment.ranking-items} terminal={story.moment.ranking-end}
+<ranking:Column id="priorities" map={speech.semanticMap} space={speech.space} canvas={vertical}
+ frame={layout.ranking} during={story.segment.ranking}
style={ranking-style}>
- <ranking:ColumnItem label={winner}/>
+ <ranking:ColumnItem rank="1" label={winner}
+ during={story.selection.winner-reveal}/>
+ <ranking:ColumnItem rank="2" preset="true" label="Already placed"/>
</ranking:Column>
```
+
+Column separates placement from reveal time. `rank` determines the numbered row only. Every
+non-preset Item owns one Selection whose projected window is its preferred reveal interval; the
+Column resolves those sibling candidates into non-overlapping windows inside the container's
+Segment/Selection `during` span. Candidate time, child order and rank may all differ. A preset Item
+has no child `during` and is settled from the beginning of the outer window.
+
+The Column's `frame` is the fixed left ranking rail; `canvas` supplies the independent coordinate
+space for the large reveal stage. `stage-x` and `stage-y` are normalized Canvas coordinates. Each
+normal reveal rises from below the Canvas, holds on that stage, then shrinks and moves into its
+ranked content slot.
diff --git a/packages/ranking/src/component.ts b/packages/ranking/src/component.ts
index 4345af96..61321313 100644
--- a/packages/ranking/src/component.ts
+++ b/packages/ranking/src/component.ts
@@ -1,15 +1,15 @@
import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
import type { SynchronizedMedia } from "@hypit/media";
-import type { NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
+import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
import type { ProgramSpace } from "@hypit/program-space";
import { canonicalize } from "@hypit/protocol";
import type { BlobRef, StoredValue } from "@hypit/protocol";
import type { CompleteSemanticMap } from "@hypit/semantic-map";
-import type { SpatialFrame } from "@hypit/spatial";
+import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
import type { Text } from "@hypit/text";
import { rankingProducers, rankingTypes } from "./manifest.js";
-import { appendColumnItem, appendRankingItemSpec, appendRankingSound, appendTierBoardItem, appendTopThreeItem, assertColumnProgram, assertRankingSchedule, assertRankingSoundEventPlan, assertTierBoardProgram, assertTopThreeProgram, buildColumnProgram, buildColumnSoundEvents, buildRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, materializeRankingTextItem } from "./schedule.js";
+import { appendColumnItem, appendColumnWindowCandidate, appendRankingItemSpec, appendRankingSound, appendTierBoardItem, appendTopThreeItem, assertColumnProgram, assertRankingSchedule, assertRankingSoundEventPlan, assertTierBoardProgram, assertTopThreeProgram, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowCandidateSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, materializeRankingTextItem, projectColumnSegmentOuterWindow, projectColumnSelectionOuterWindow } from "./schedule.js";
import {
renderColumn,
renderRankingAudio,
@@ -19,8 +19,10 @@ import {
import type {
ColumnItemSet,
ColumnItemSpec,
+ ColumnOuterWindow,
ColumnProgram,
ColumnStyle,
+ ColumnWindowCandidateSet,
RankingHeader,
RankingItemSpec,
RankingItemSpecSet,
@@ -87,6 +89,45 @@ export const rankingComponent = {
terminal: inline(inputs.terminal?.value, "NarrativeMomentRef"),
})) }, needs: {} }),
},
+ {
+ producer: rankingProducers.projectColumnSelectionOuter,
+ handler: ({ inputs }) => ({ outputs: { outer: output(projectColumnSelectionOuterWindow(
+ inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelectionRef"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: rankingProducers.projectColumnSegmentOuter,
+ handler: ({ inputs }) => ({ outputs: { outer: output(projectColumnSegmentOuterWindow(
+ inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: rankingProducers.createColumnCandidates,
+ handler: () => ({ outputs: { set: output(createColumnWindowCandidateSet()) }, needs: {} }),
+ },
+ {
+ producer: rankingProducers.appendColumnCandidate,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendColumnWindowCandidate(
+ inline<ColumnWindowCandidateSet>(inputs.set?.value, "ColumnWindowCandidateSet"),
+ inline<ColumnItemSpec>(inputs.spec?.value, "ColumnItemSpec"),
+ inline<CompleteSemanticMap>(inputs.map?.value, "CompleteSemanticMap"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelectionRef"),
+ )) }, needs: {} }),
+ },
+ {
+ producer: rankingProducers.columnSchedule,
+ handler: ({ inputs }) => ({ outputs: { schedule: output(buildColumnSchedule({
+ header: inline<RankingHeader>(inputs.header?.value, "RankingHeader"),
+ items: inline<RankingItemSpecSet>(inputs.items?.value, "RankingItemSpecSet"),
+ outer: inline<ColumnOuterWindow>(inputs.outer?.value, "ColumnOuterWindow"),
+ candidates: inline<ColumnWindowCandidateSet>(inputs.candidates?.value, "ColumnWindowCandidateSet"),
+ })) }, needs: {} }),
+ },
...([
[rankingProducers.createTierItems, createTierBoardItemSet],
[rankingProducers.createColumnItems, createColumnItemSet],
@@ -137,7 +178,8 @@ export const rankingComponent = {
producer: rankingProducers.columnProgram,
handler: ({ inputs }) => {
const common = programInputs(inputs);
- return { outputs: { program: output(buildColumnProgram(common.header, common.frame, common.schedule,
+ return { outputs: { program: output(buildColumnProgram(common.header,
+ inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), common.frame, common.schedule,
inline<ColumnStyle>(inputs.style?.value, "ColumnStyle"), inline<ColumnItemSet>(inputs.set?.value, "ColumnItemSet"))) }, needs: {} };
},
},
diff --git a/packages/ranking/src/fragment.ts b/packages/ranking/src/fragment.ts
index ae9db281..df153c1c 100644
--- a/packages/ranking/src/fragment.ts
+++ b/packages/ranking/src/fragment.ts
@@ -19,6 +19,7 @@ export type RankingFragmentItem = {
readonly specName: string;
readonly iconName?: string;
readonly contentName?: string;
+ readonly timingName?: string;
};
export type RankingFragmentSound = {
@@ -39,19 +40,19 @@ const definition = (variant: RankingVariant) => {
appendIcon: rankingProducers.appendColumnIconItem, build: rankingProducers.columnProgram,
events: rankingProducers.columnEvents, render: rankingProducers.renderColumn,
} as const;
- if (variant === "top-three") return {
+ return {
style: rankingTypes.topThreeStyle, set: rankingTypes.topThreeItems, program: rankingTypes.topThreeProgram,
create: rankingProducers.createTopThreeItems, append: rankingProducers.appendTopThreeItem,
appendIcon: rankingProducers.appendTopThreeIconItem, build: rankingProducers.topThreeProgram,
events: rankingProducers.topThreeEvents, render: rankingProducers.renderTopThree,
} as const;
- throw new Error(`Ranking Fragment has no definition for variant ${variant as string}.`);
};
export function createRankingFragment(
variant: RankingVariant,
items: readonly RankingFragmentItem[],
sound: RankingFragmentSound,
+ outerKind: "selection" | "segment" = "selection",
) {
if (items.length === 0) throw new Error("Ranking Fragment requires at least one Item.");
const selected = definition(variant);
@@ -59,22 +60,28 @@ export function createRankingFragment(
{ name: "header", type: rankingTypes.header },
{ name: "map", type: semanticMapTypes.complete },
{ name: "space", type: programSpaceTypes.programSpace },
- { name: "outer", type: narrativeTypes.selection },
- { name: "triggers", type: narrativeTypes.moment },
- { name: "terminal", type: narrativeTypes.moment },
+ { name: "outer", type: outerKind === "selection" ? narrativeTypes.selection : narrativeTypes.excerpt },
+ ...(variant === "column" ? [] : [
+ { name: "triggers", type: narrativeTypes.moment },
+ { name: "terminal", type: narrativeTypes.moment },
+ ]),
+ ...(variant === "column" ? [{ name: "canvas", type: spatialTypes.canvas }] : []),
{ name: "frame", type: spatialTypes.frame },
{ name: "style", type: selected.style },
];
const operations: FragmentOperation[] = [
{ id: "specs", producer: rankingProducers.createSpecs, inputs: { header: input("header") }, result: { kind: "output", name: "set" } },
{ id: "resolved", producer: selected.create, inputs: {}, result: { kind: "output", name: "set" } },
+ ...(variant === "column" ? [{ id: "candidates", producer: rankingProducers.createColumnCandidates, inputs: {}, result: { kind: "output" as const, name: "set" } }] : []),
];
let specs = operation("specs");
let resolved = operation("resolved");
+ let candidates = operation("candidates");
for (const item of items) {
inputs.push({ name: item.specName, type: item.contentName === undefined ? rankingTypes.itemSpec : rankingTypes.textItemShell });
if (item.contentName !== undefined) inputs.push({ name: item.contentName, type: textTypes.text });
if (item.iconName !== undefined) inputs.push({ name: item.iconName, type: mediaTypes.blobArtifact });
+ if (item.timingName !== undefined) inputs.push({ name: item.timingName, type: narrativeTypes.selection });
const materializedId = `materialize-${item.suffix}`;
if (item.contentName !== undefined) operations.push({
id: materializedId,
@@ -103,21 +110,47 @@ export function createRankingFragment(
result: { kind: "output", name: "set" },
});
resolved = operation(visualId);
+ if (item.timingName !== undefined) {
+ const timingId = `timing-${item.suffix}`;
+ operations.push({
+ id: timingId,
+ producer: rankingProducers.appendColumnCandidate,
+ inputs: {
+ set: candidates, spec: resolvedSpec, map: input("map"), space: input("space"), selection: input(item.timingName),
+ },
+ result: { kind: "output", name: "set" },
+ });
+ candidates = operation(timingId);
+ }
}
- operations.push({
- id: "schedule",
- producer: rankingProducers.schedule,
- inputs: {
- header: input("header"), items: specs, map: input("map"), space: input("space"),
- outer: input("outer"), triggers: input("triggers"), terminal: input("terminal"),
- },
- result: { kind: "output", name: "schedule" },
- });
+ if (variant === "column") {
+ operations.push({
+ id: "outer-window",
+ producer: outerKind === "selection" ? rankingProducers.projectColumnSelectionOuter : rankingProducers.projectColumnSegmentOuter,
+ inputs: { map: input("map"), space: input("space"), [outerKind]: input("outer") },
+ result: { kind: "output", name: "outer" },
+ });
+ operations.push({
+ id: "schedule",
+ producer: rankingProducers.columnSchedule,
+ inputs: { header: input("header"), items: specs, outer: operation("outer-window"), candidates },
+ result: { kind: "output", name: "schedule" },
+ });
+ } else operations.push({
+ id: "schedule",
+ producer: rankingProducers.schedule,
+ inputs: {
+ header: input("header"), items: specs, map: input("map"), space: input("space"),
+ outer: input("outer"), triggers: input("triggers"), terminal: input("terminal"),
+ },
+ result: { kind: "output", name: "schedule" },
+ });
operations.push({
id: "program",
producer: selected.build,
inputs: {
header: input("header"),
+ ...(variant === "column" ? { canvas: input("canvas") } : {}),
frame: input("frame"), schedule: operation("schedule"), style: input("style"), set: resolved,
},
result: { kind: "output", name: "program" },
diff --git a/packages/ranking/src/index.ts b/packages/ranking/src/index.ts
index 13a2c929..7fe4bf95 100644
--- a/packages/ranking/src/index.ts
+++ b/packages/ranking/src/index.ts
@@ -1,4 +1,4 @@
-export { appendRankingItemSpec, appendRankingSound, appendColumnItem, appendTierBoardItem, appendTopThreeItem, assertColumnProgram, assertColumnStyle, assertRankingHeader, assertRankingItemSpec, assertRankingItemSpecSet, assertRankingTextItemShell, assertRankingSchedule, assertRankingSoundEventPlan, assertRankingSoundStyle, assertTierBoardProgram, assertTierBoardStyle, assertTopThreeProgram, assertTopThreeStyle, buildColumnProgram, buildColumnSoundEvents, buildRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, sealRankingHeader, sealRankingTextItemShell, materializeRankingTextItem } from "./schedule.js";
+export { appendColumnWindowCandidate, appendRankingItemSpec, appendRankingSound, appendColumnItem, appendTierBoardItem, appendTopThreeItem, assertColumnProgram, assertColumnStyle, assertColumnWindowCandidateSet, assertRankingHeader, assertRankingItemSpec, assertRankingItemSpecSet, assertRankingTextItemShell, assertRankingSchedule, assertRankingSoundEventPlan, assertRankingSoundStyle, assertTierBoardProgram, assertTierBoardStyle, assertTopThreeProgram, assertTopThreeStyle, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowCandidateSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, projectColumnSegmentOuterWindow, projectColumnSelectionOuterWindow, sealRankingHeader, sealRankingTextItemShell, materializeRankingTextItem } from "./schedule.js";
export {
decodeColumnStyle,
decodeTierBoardStyle,
@@ -13,7 +13,7 @@ export {
export { rankingComponent } from "./component.js";
export { createRankingFragment } from "./fragment.js";
export type { RankingFragmentItem, RankingFragmentSound } from "./fragment.js";
-export { rankingDependency, rankingHeaderSchema, rankingItemSpecSchema, rankingTextItemShellSchema, rankingItemSpecSetSchema, rankingManifest, rankingMarkupSurfaces, rankingModuleRef, rankingProducers, rankingScheduleSchema, rankingSoundEventsSchema, rankingSoundSetSchema, rankingSoundStyleSchema, rankingTypes } from "./manifest.js";
+export { columnOuterWindowSchema, columnWindowCandidateSetSchema, rankingDependency, rankingHeaderSchema, rankingItemSpecSchema, rankingTextItemShellSchema, rankingItemSpecSetSchema, rankingManifest, rankingMarkupSurfaces, rankingModuleRef, rankingProducers, rankingScheduleSchema, rankingSoundEventsSchema, rankingSoundSetSchema, rankingSoundStyleSchema, rankingTypes } from "./manifest.js";
export {
decodeColumnStyleSurface,
decodeColumnSurface,
diff --git a/packages/ranking/src/manifest.ts b/packages/ranking/src/manifest.ts
index c2929845..dbd22498 100644
--- a/packages/ranking/src/manifest.ts
+++ b/packages/ranking/src/manifest.ts
@@ -24,6 +24,8 @@ export const rankingTypes = {
itemSpec: { module: rankingModuleRef, name: "RankingItemSpec" },
textItemShell: { module: rankingModuleRef, name: "RankingTextItemShell" },
itemSpecs: { module: rankingModuleRef, name: "RankingItemSpecSet" },
+ columnOuter: { module: rankingModuleRef, name: "ColumnOuterWindow" },
+ columnCandidates: { module: rankingModuleRef, name: "ColumnWindowCandidateSet" },
schedule: { module: rankingModuleRef, name: "RankingSchedule" },
soundStyle: { module: rankingModuleRef, name: "RankingSoundStyle" },
soundEvents: { module: rankingModuleRef, name: "RankingSoundEventPlan" },
@@ -43,6 +45,11 @@ export const rankingProducers = {
createSpecs: { module: rankingModuleRef, name: "create-ranking-item-specs" },
appendSpec: { module: rankingModuleRef, name: "append-ranking-item-spec" },
schedule: { module: rankingModuleRef, name: "build-ranking-schedule" },
+ projectColumnSelectionOuter: { module: rankingModuleRef, name: "project-column-selection-outer" },
+ projectColumnSegmentOuter: { module: rankingModuleRef, name: "project-column-segment-outer" },
+ createColumnCandidates: { module: rankingModuleRef, name: "create-column-window-candidates" },
+ appendColumnCandidate: { module: rankingModuleRef, name: "append-column-window-candidate" },
+ columnSchedule: { module: rankingModuleRef, name: "build-column-schedule" },
createTierItems: { module: rankingModuleRef, name: "create-tier-board-items" },
appendTierItem: { module: rankingModuleRef, name: "append-tier-board-item" },
createColumnItems: { module: rankingModuleRef, name: "create-column-items" },
@@ -83,11 +90,15 @@ export const rankingHeaderSchema: ValueSchema = object({
});
export const rankingItemSpecSchema: ValueSchema = { kind: "oneOf", variants: [
object({ variant: { schema: { kind: "literal", value: "tier-board" } }, ...itemBase, tier: { schema: string }, entry: { schema: { kind: "string", enum: ["direct", "stage"] } } }),
- object({ variant: { schema: { kind: "literal", value: "column" } }, ...itemBase, label: { schema: string } }),
+ object({ variant: { schema: { kind: "literal", value: "column" } }, ...itemBase,
+ label: { schema: string }, rank: { schema: { kind: "number", integer: true, minimum: 1 } }, preset: { schema: { kind: "boolean" } },
+ }),
object({ variant: { schema: { kind: "literal", value: "top-three" } }, ...itemBase, label: { schema: string } }),
] };
export const rankingTextItemShellSchema: ValueSchema = { kind: "oneOf", variants: [
- object({ variant: { schema: { kind: "literal", value: "column" } }, ...itemBase }),
+ object({ variant: { schema: { kind: "literal", value: "column" } }, ...itemBase,
+ rank: { schema: { kind: "number", integer: true, minimum: 1 } }, preset: { schema: { kind: "boolean" } },
+ }),
object({ variant: { schema: { kind: "literal", value: "top-three" } }, ...itemBase }),
] };
export const rankingItemSpecSetSchema: ValueSchema = object({
@@ -95,14 +106,31 @@ export const rankingItemSpecSetSchema: ValueSchema = object({
variant: { schema: variants }, items: { schema: { kind: "array", items: rankingItemSpecSchema } },
});
const frameSpan = object({ startFrame: { schema: unsigned }, endFrameExclusive: { schema: unsigned } });
-export const rankingScheduleSchema: ValueSchema = object({
+export const columnOuterWindowSchema: ValueSchema = object({ span: { schema: frameSpan } });
+export const columnWindowCandidateSetSchema: ValueSchema = object({
+ entries: { schema: { kind: "array", items: object({
+ itemId: { schema: string }, occurrenceId: { schema: string }, preferred: { schema: frameSpan },
+ }) } },
+});
+const triggeredScheduleSchema: ValueSchema = object({
id: { schema: string },
- variant: { schema: variants }, outer: { schema: frameSpan }, terminalFrame: { schema: unsigned },
+ variant: { schema: { kind: "string", enum: ["tier-board", "top-three"] } },
+ outer: { schema: frameSpan }, terminalFrame: { schema: unsigned },
entries: { schema: { kind: "array", minItems: 1, items: object({
itemId: { schema: string }, triggerFrame: { schema: unsigned },
stage: { schema: frameSpan }, cumulative: { schema: frameSpan }, settled: { schema: frameSpan },
}) } },
});
+const columnScheduleSchema: ValueSchema = object({
+ id: { schema: string }, variant: { schema: { kind: "literal", value: "column" } }, outer: { schema: frameSpan },
+ entries: { schema: { kind: "array", minItems: 1, items: { kind: "oneOf", variants: [
+ object({ itemId: { schema: string }, mode: { schema: { kind: "literal", value: "preset" } }, settled: { schema: frameSpan } }),
+ object({ itemId: { schema: string }, mode: { schema: { kind: "literal", value: "reveal" } },
+ preferred: { schema: frameSpan }, active: { schema: frameSpan }, settled: { schema: frameSpan },
+ }),
+ ] } } },
+});
+export const rankingScheduleSchema: ValueSchema = { kind: "oneOf", variants: [triggeredScheduleSchema, columnScheduleSchema] };
const styleSchema = (): ValueSchema => object({}, true);
const setSchema = (): ValueSchema => object({
items: { schema: { kind: "array", items: object({}, true) } },
@@ -459,9 +487,9 @@ export const rankingMarkupSurfaces = [
} },
{ name: "column", tag: "Column", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, rankingTypes.schedule, rankingTypes.columnProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],
vocabulary: {
- summary: "Fills a ranked column one row at a time, one on each occurrence of a Moment, and publishes the board and the Tracks it renders to.",
+ summary: "Places rows by explicit rank, reveals each non-preset row in its own Selection, and publishes the board and the Tracks it renders to.",
appearance:
- "One rounded, bordered, shadowed board filling its Frame, carrying an empty slat for every Item from the first frame: a full-width rounded row washed and outlined in that rank's color, with its rank number set at the left end in the same color. The slats sit as one block pushed to the bottom of the board, and a hollow rounded staging square waits near the top of the Frame. Each Item appears inside that square at stage size, then shrinks and slides into its own slat, filling from the top slat downward, one row per trigger occurrence in document order. A filled row reads as its optional icon and then its label, set left-aligned along the slat, and holds there once it settles.",
+ "A narrow vertical rank rail occupies its Frame while a large reveal stage is positioned independently in Canvas space. Preset rows are settled from the first frame. Each other row rises into the stage during its own projected Selection, then shrinks and moves into the content slot beside its numbered rank. Rank, child order and reveal time are independent.",
preview: previewImage("Column.png"),
attributes: [
{ name: "id", kind: "identifier", required: true,
@@ -470,14 +498,12 @@ export const rankingMarkupSurfaces = [
summary: "Chooses the measured SemanticMap that gives every trigger its frame." },
{ name: "space", kind: "reference", required: true, accepts: [programSpaceTypes.programSpace],
summary: "Chooses the ProgramSpace the board is timed and rendered against." },
+ { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
+ summary: "Chooses the Canvas coordinate space used by the independent reveal stage." },
{ name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
- summary: "Chooses the Frame the whole board occupies." },
- { name: "during", kind: "reference", required: true, accepts: [narrativeTypes.selection],
- summary: "Chooses the Selection the board is on screen for." },
- { name: "triggers", kind: "reference", required: true, accepts: [narrativeTypes.moment],
- summary: "Chooses the Moment whose occurrences place one ColumnItem each, in document order." },
- { name: "terminal", kind: "reference", required: true, accepts: [narrativeTypes.moment],
- summary: "Chooses the Moment the board settles on and ends after." },
+ summary: "Chooses the fixed Frame occupied by the vertical rank rail." },
+ { name: "during", kind: "reference", required: true, accepts: [narrativeTypes.selection, narrativeTypes.excerpt],
+ summary: "Chooses the Segment or Selection that contains the complete Column lifetime." },
{ name: "style", kind: "reference", required: true, accepts: [rankingTypes.columnStyle],
summary: "Chooses the ColumnStyle this board is drawn in, and only that variant's." },
{ name: "appear-sound", kind: "reference", required: false, accepts: [mediaTypes.synchronized],
@@ -487,12 +513,18 @@ export const rankingMarkupSurfaces = [
],
children: [
{ tag: "ColumnItem", cardinality: "many",
- summary: "One row of the column, placed at its own trigger occurrence in document order; it is empty.",
+ summary: "One explicitly ranked row; it is either preset or owns one reveal Selection.",
attributes: [
{ name: "id", kind: "identifier", required: false,
summary: "Names this row within the board; an omitted id is generated from the row's position." },
{ name: "label", kind: "expression", required: true, accepts: [textTypes.text],
summary: "Sets the row's copy, written literally or chosen from an existing Text." },
+ { name: "rank", kind: "literal", required: true,
+ summary: "Sets the positive rank number and final row position independently from reveal order." },
+ { name: "preset", kind: "literal", required: false, values: ["true", "false"],
+ summary: "Settles the row from the start of the outer window; defaults to false." },
+ { name: "during", kind: "reference", required: false, accepts: [narrativeTypes.selection],
+ summary: "Chooses this row's preferred reveal Selection; required unless preset is true." },
{ name: "icon", kind: "reference", required: false, accepts: [mediaTypes.blobArtifact],
summary: "Chooses the image drawn beside the row." },
{ name: "stack", kind: "literal", required: false,
@@ -501,7 +533,7 @@ export const rankingMarkupSurfaces = [
],
ports: [
{ name: "schedule", type: rankingTypes.schedule,
- summary: "The resolved Schedule: each Item's trigger frame and its staged, cumulative and settled spans." },
+ summary: "The resolved Schedule: preset spans and non-overlapping reveal windows inside the outer lifetime." },
{ name: "program", type: rankingTypes.columnProgram,
summary: "The resolved board: its Frame, Style, Schedule and ordered Items." },
{ name: "visual", type: compositionTypes.visualTrack,
@@ -510,15 +542,17 @@ export const rankingMarkupSurfaces = [
summary: "The rendered board sound, published only when a sound is authored." },
],
example: `<ranking:ColumnStyle id="board-style" recipe={studio.ranking.board} font={ui-font}/>
-<ranking:Column id="board" map={timing.map} space={speech.space} frame={board-frame}
- during={story.selection.board} triggers={story.moment.place} terminal={story.moment.done}
+<ranking:Column id="board" map={timing.map} space={speech.space} canvas={vertical} frame={board-frame}
+ during={story.segment.ranking}
style={board-style}>
- <ranking:ColumnItem id="row-regen" label="ReGen" icon={icon-regen}/>
- <ranking:ColumnItem id="row-chatgpt" label="ChatGPT" icon={icon-chatgpt}/>
- <ranking:ColumnItem id="row-remini" label="Remini" icon={icon-remini}/>
+ <ranking:ColumnItem id="row-regen" rank="1" label="ReGen" icon={icon-regen} during={story.selection.regen}/>
+ <ranking:ColumnItem id="row-chatgpt" rank="2" label="ChatGPT" icon={icon-chatgpt} during={story.selection.chatgpt}/>
+ <ranking:ColumnItem id="row-remini" rank="5" preset="true" label="Remini" icon={icon-remini}/>
</ranking:Column>`,
notes: [
"The board requires at least one ColumnItem, accepts no other child and no text of its own, and Item ids must be unique within it.",
+ "Ranks must be unique; child order does not determine either final placement or reveal order.",
+ "Non-preset Selection windows are clamped to the outer window and resolved into non-overlapping intervals; preset Items have no child `during`.",
"A `label` written as a reference materializes the row from that exact Text before the board is scheduled.",
"Authoring either sound also connects the Style's `.sound` output, so `style` must name a ColumnStyle written in this Source.",
],
@@ -600,6 +634,8 @@ export const rankingManifest: ModuleManifest = {
{ name: rankingTypes.itemSpec.name },
{ name: rankingTypes.textItemShell.name },
{ name: rankingTypes.itemSpecs.name },
+ { name: rankingTypes.columnOuter.name },
+ { name: rankingTypes.columnCandidates.name },
{ name: rankingTypes.schedule.name },
{ name: rankingTypes.soundStyle.name },
{ name: rankingTypes.soundEvents.name },
@@ -624,6 +660,26 @@ export const rankingManifest: ModuleManifest = {
{ name: "map", type: semanticMapTypes.complete }, { name: "space", type: programSpaceTypes.programSpace },
{ name: "outer", type: narrativeTypes.selection }, { name: "triggers", type: narrativeTypes.moment }, { name: "terminal", type: narrativeTypes.moment },
], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [] },
+ { name: rankingProducers.projectColumnSelectionOuter.name, inputs: [
+ { name: "map", type: semanticMapTypes.complete }, { name: "space", type: programSpaceTypes.programSpace },
+ { name: "selection", type: narrativeTypes.selection },
+ ], outputs: [{ name: "outer", type: rankingTypes.columnOuter }], needs: [] },
+ { name: rankingProducers.projectColumnSegmentOuter.name, inputs: [
+ { name: "map", type: semanticMapTypes.complete }, { name: "space", type: programSpaceTypes.programSpace },
+ { name: "segment", type: narrativeTypes.excerpt },
+ ], outputs: [{ name: "outer", type: rankingTypes.columnOuter }], needs: [] },
+ { name: rankingProducers.createColumnCandidates.name, inputs: [], outputs: [
+ { name: "set", type: rankingTypes.columnCandidates },
+ ], needs: [] },
+ { name: rankingProducers.appendColumnCandidate.name, inputs: [
+ { name: "set", type: rankingTypes.columnCandidates }, { name: "spec", type: rankingTypes.itemSpec },
+ { name: "map", type: semanticMapTypes.complete }, { name: "space", type: programSpaceTypes.programSpace },
+ { name: "selection", type: narrativeTypes.selection },
+ ], outputs: [{ name: "set", type: rankingTypes.columnCandidates }], needs: [] },
+ { name: rankingProducers.columnSchedule.name, inputs: [
+ { name: "header", type: rankingTypes.header }, { name: "items", type: rankingTypes.itemSpecs },
+ { name: "outer", type: rankingTypes.columnOuter }, { name: "candidates", type: rankingTypes.columnCandidates },
+ ], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [] },
...([
[rankingProducers.createTierItems, rankingTypes.tierItems],
[rankingProducers.createColumnItems, rankingTypes.columnItems],
@@ -647,6 +703,7 @@ export const rankingManifest: ModuleManifest = {
...programDefinitions.flatMap(([programType, styleType, setType, programProducer, eventProducer, renderProducer]) => [
{ name: programProducer.name, inputs: [
{ name: "header", type: rankingTypes.header },
+ ...(programType === rankingTypes.columnProgram ? [{ name: "canvas", type: spatialTypes.canvas }] : []),
{ name: "frame", type: spatialTypes.frame }, { name: "schedule", type: rankingTypes.schedule },
{ name: "style", type: styleType }, { name: "set", type: setType },
], outputs: [{ name: "program", type: programType }], needs: [] },
diff --git a/packages/ranking/src/render.ts b/packages/ranking/src/render.ts
index 229d5229..7aa92abd 100644
--- a/packages/ranking/src/render.ts
+++ b/packages/ranking/src/render.ts
@@ -27,6 +27,7 @@ import {
assertRankingSoundStyle,
assertTierBoardProgram,
assertTopThreeProgram,
+ fitColumnRevealMotion,
fitRankingStageMotion,
} from "./schedule.js";
import type {
@@ -349,89 +350,184 @@ function rankColor(colors: readonly string[], index: number): string {
return colors[index % colors.length]!;
}
+function columnCardTransform(input: {
+ readonly finalCenterX: number;
+ readonly finalCenterY: number;
+ readonly centerX: number;
+ readonly centerY: number;
+ readonly size: number;
+ readonly finalSize: number;
+ readonly scale?: number;
+}): string {
+ const translateX = input.centerX - input.finalCenterX;
+ const translateY = input.centerY - input.finalCenterY;
+ const scale = Math.round(input.size / input.finalSize * (input.scale ?? 1) * 1_000_000) / 1_000_000;
+ return `translate(${px(translateX)},${px(translateY)}) scale(${scale})`;
+}
+
+function lerp(from: number, to: number, progress: number): number {
+ return from + (to - from) * progress;
+}
+
+function outBack(progress: number): number {
+ const c1 = 1.70158;
+ const c3 = c1 + 1;
+ return 1 + c3 * Math.pow(progress - 1, 3) + c1 * Math.pow(progress - 1, 2);
+}
+
+function columnRevealAnimation(input: {
+ readonly duration: number;
+ readonly appearFrames: number;
+ readonly moveFrames: number;
+ readonly finalCenterX: number;
+ readonly finalCenterY: number;
+ readonly stageCenterX: number;
+ readonly stageCenterY: number;
+ readonly entryCenterY: number;
+ readonly stageSize: number;
+ readonly finalSize: number;
+ readonly easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+}): VisualAnimation {
+ const moveStart = input.duration - input.moveFrames;
+ const moveEnd = Math.max(moveStart, input.duration - 1);
+ const holdFrames = moveStart - input.appearFrames;
+ const stage = (centerX = input.stageCenterX, centerY = input.stageCenterY, scale = 1) => columnCardTransform({
+ finalCenterX: input.finalCenterX,
+ finalCenterY: input.finalCenterY,
+ centerX,
+ centerY,
+ size: input.stageSize,
+ finalSize: input.finalSize,
+ scale,
+ });
+ const overshootFrame = Math.max(1, Math.round(input.appearFrames * 0.72));
+ const overshootProgress = outBack(overshootFrame / input.appearFrames);
+ return animation(input.duration, [
+ { atFrame: 0, style: transformStyle(columnCardTransform({
+ finalCenterX: input.finalCenterX,
+ finalCenterY: input.finalCenterY,
+ centerX: input.stageCenterX,
+ centerY: input.entryCenterY,
+ size: input.stageSize,
+ finalSize: input.finalSize,
+ scale: 0.96,
+ }), 0), easing: "ease-out" },
+ ...(overshootFrame < input.appearFrames ? [{
+ atFrame: overshootFrame,
+ style: transformStyle(stage(input.stageCenterX,
+ lerp(input.entryCenterY, input.stageCenterY, overshootProgress),
+ 0.96 + 0.04 * overshootProgress), 1),
+ easing: "ease-in-out" as const,
+ }] : []),
+ { atFrame: input.appearFrames, style: transformStyle(stage(), 1) },
+ ...(holdFrames >= 6 ? [
+ { atFrame: input.appearFrames + Math.floor(holdFrames / 3),
+ style: transformStyle(stage(input.stageCenterX + 0.8, input.stageCenterY - 1.8, 1.007), 1), easing: "ease-in-out" as const },
+ { atFrame: input.appearFrames + Math.floor(holdFrames * 2 / 3),
+ style: transformStyle(stage(input.stageCenterX - 0.4, input.stageCenterY + 1.6, 1.002), 1), easing: "ease-in-out" as const },
+ ] : []),
+ { atFrame: moveStart, style: transformStyle(stage(), 1), easing: input.easing },
+ { atFrame: moveEnd, style: transformStyle(finalTransform(), 1) },
+ ]);
+}
+
export function renderColumn(space: ProgramSpace, program: ColumnProgram): VisualTrack {
assertProgramSpaceIdentity(space);
assertColumnProgram(program);
- const { frame, style, schedule } = program;
+ const { canvas, frame, style, schedule } = program;
const presents: VisualPresent[] = [];
+ const entries = new Map(schedule.entries.map((entry) => [entry.itemId, entry]));
+ const cellSize = style.rowHeightPx;
+ const columnGap = Math.max(8, Math.round(cellSize * 0.16));
+ const contentSize = Math.min(cellSize, frame.widthPx - style.paddingPx * 2 - cellSize - columnGap);
+ assert(contentSize > 0, "Column Frame is too narrow for its rank and content cells.");
+ const requiredHeight = style.paddingPx * 2 + program.items.length * cellSize
+ + Math.max(0, program.items.length - 1) * style.rowGapPx;
+ assert(requiredHeight <= frame.heightPx, "Column rows do not fit inside its Frame.");
const boardElements: VisualElement[] = [absoluteBox({
id: "column-board", order: 0, x: frame.xPx, y: frame.yPx, width: frame.widthPx, height: frame.heightPx,
style: boardStyle(style.board),
})];
- for (const [index] of program.items.entries()) {
- const y = rowY(0, frame.heightPx, style.paddingPx, program.items.length, index, style.rowHeightPx, style.rowGapPx);
+ for (const [index, item] of program.items.entries()) {
+ const y = style.paddingPx + index * (cellSize + style.rowGapPx);
+ const color = rankColor(style.rankColors, item.rank - 1);
boardElements.push(absoluteBox({
- id: `column-row-${index + 1}`, parent: "column-board", order: boardElements.length,
- x: style.paddingPx, y, width: frame.widthPx - style.paddingPx * 2, height: style.rowHeightPx,
+ id: `column-rank-cell-${item.rank}`, parent: "column-board", order: boardElements.length,
+ x: style.paddingPx, y, width: cellSize, height: cellSize,
style: [
- { name: "background", value: `${rankColor(style.rankColors, index)}22` },
- { name: "border", value: `${px(1)} solid ${rankColor(style.rankColors, index)}88` },
- { name: "border-radius", value: px(12) },
+ { name: "background", value: color },
+ { name: "border-radius", value: px(Math.max(4, Math.round(cellSize * 0.075))) },
],
}));
boardElements.push(simpleText({
- id: `column-rank-${index + 1}`, parent: `column-row-${index + 1}`, order: boardElements.length,
- text: String(index + 1), typography: { ...style.text, color: rankColor(style.rankColors, index) },
- x: 0, y: 0, width: style.rowHeightPx, height: style.rowHeightPx,
+ id: `column-rank-${item.rank}`, parent: `column-rank-cell-${item.rank}`, order: boardElements.length,
+ text: String(item.rank), typography: { ...style.text, color: "#ffffff", sizePx: Math.max(style.text.sizePx, cellSize * 0.48) },
+ x: 0, y: 0, width: cellSize, height: cellSize,
+ }));
+ boardElements.push(absoluteBox({
+ id: `column-content-cell-${item.rank}`, parent: "column-board", order: boardElements.length,
+ x: style.paddingPx + cellSize + columnGap, y, width: contentSize, height: contentSize,
+ style: [
+ { name: "background", value: "#000000b8" },
+ { name: "border", value: `${px(1.5)} solid #ffffff2e` },
+ { name: "border-radius", value: px(Math.min(style.iconRadiusPx, contentSize / 2)) },
+ { name: "box-sizing", value: "border-box" },
+ { name: "overflow", value: "hidden" },
+ ],
}));
}
presents.push(present({ id: `${program.id}:board`, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,
stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:board`, elements: boardElements }));
- const stageSize = style.stageSizePx;
- presents.push(present({
- id: `${program.id}:stage`, start: schedule.entries[0]!.triggerFrame, end: schedule.terminalFrame,
- stacking: style.stageStackingOrder, tieBreak: `${program.id}:0001:stage`, elements: [absoluteBox({
- id: "column-stage", order: 0,
- x: frame.xPx + frame.widthPx * style.stagePoint.x - stageSize / 2,
- y: frame.yPx + frame.heightPx * style.stagePoint.y - stageSize / 2,
- width: stageSize, height: stageSize,
- style: [{ name: "border", value: `${px(2)} solid ${style.text.color}66` }, { name: "border-radius", value: px(18) }],
- })],
- }));
for (const [index, item] of program.items.entries()) {
- const entry = schedule.entries[index]!;
- const x = frame.xPx + style.paddingPx;
- const y = rowY(frame.yPx, frame.heightPx, style.paddingPx, program.items.length, index, style.rowHeightPx, style.rowGapPx);
- const width = frame.widthPx - style.paddingPx * 2;
- const duration = entry.stage.endFrameExclusive - entry.triggerFrame;
- const fitted = fitRankingStageMotion(duration, style.motion.appearFrames, style.motion.moveFrames, true);
- const targetStageX = frame.xPx + frame.widthPx * style.stagePoint.x - width / 2;
- const targetStageY = frame.yPx + frame.heightPx * style.stagePoint.y - style.rowHeightPx / 2;
+ const entry = entries.get(item.id)!;
+ const x = frame.xPx + style.paddingPx + cellSize + columnGap;
+ const y = frame.yPx + style.paddingPx + index * (cellSize + style.rowGapPx);
+ const finalCenterX = x + contentSize / 2;
+ const finalCenterY = y + contentSize / 2;
+ const stageCenterX = Math.round(canvas.widthPx * style.stagePoint.x);
+ const stageCenterY = Math.round(canvas.heightPx * style.stagePoint.y);
+ const entryCenterY = canvas.heightPx + style.stageSizePx * 0.25;
const root = `column-item-${item.id}`;
- const rootAnimation = settledItemAnimation({
- duration,
- appearFrames: fitted.appearFrames,
- moveStart: entry.stage.endFrameExclusive - fitted.moveFrames - entry.triggerFrame,
- moveEnd: entry.stage.endFrameExclusive - entry.triggerFrame,
- stageTransform: stageTransform(x, y, targetStageX, targetStageY, style.stageSizePx / style.rowHeightPx),
- easing: style.motion.easing,
- });
const itemElements = (animationValue?: VisualAnimation): VisualElement[] => {
+ const iconSize = Math.min(style.iconSizePx, contentSize);
const elements: VisualElement[] = [absoluteBox({
- id: root, order: 0, x, y, width, height: style.rowHeightPx,
- style: [{ name: "border-radius", value: px(12) }],
+ id: root, order: 0, x, y, width: contentSize, height: contentSize,
+ style: [
+ { name: "background", value: "#fffffffa" },
+ { name: "border-radius", value: px(Math.min(style.iconRadiusPx, contentSize / 2)) },
+ { name: "overflow", value: "hidden" },
+ { name: "transform-origin", value: "center center" },
+ ],
...(animationValue === undefined ? {} : { animation: animationValue }),
})];
- if (item.icon !== undefined) elements.push(iconElement({ id: "icon", parent: root, order: 1, artifact: item.icon,
- x: style.rowHeightPx, y: (style.rowHeightPx - style.iconSizePx) / 2, size: style.iconSizePx,
+ if (item.icon !== undefined) elements.push(iconElement({ id: "icon", parent: root, order: elements.length, artifact: item.icon,
+ x: (contentSize - iconSize) / 2, y: (contentSize - iconSize) / 2, size: iconSize,
radius: style.iconRadiusPx, fit: style.iconFit }));
- elements.push(simpleText({
- id: "label", parent: root, order: elements.length, text: item.label, typography: style.text,
- x: style.rowHeightPx + (item.icon === undefined ? 0 : style.iconSizePx + 12), y: 0,
- width: width - style.rowHeightPx - (item.icon === undefined ? 8 : style.iconSizePx + 20), height: style.rowHeightPx,
- align: "left",
+ else elements.push(simpleText({
+ id: "label", parent: root, order: elements.length, text: item.label,
+ typography: { ...style.text, color: "#111315", sizePx: Math.max(12, contentSize * 0.16) },
+ x: contentSize * 0.06, y: 0, width: contentSize * 0.88, height: contentSize,
}));
return elements;
};
- presents.push(present({
- id: `${program.id}:item:${item.id}:stage`, start: entry.stage.startFrame, end: entry.stage.endFrameExclusive,
- stacking: item.stackingOrder ?? style.itemStackingOrder,
- tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:stage`, elements: itemElements(rootAnimation),
- }));
+ if (entry.mode === "reveal") {
+ const duration = entry.active.endFrameExclusive - entry.active.startFrame;
+ const fitted = fitColumnRevealMotion(duration, style.motion.appearFrames, style.motion.moveFrames);
+ const rootAnimation = fitted.mode === "direct" ? undefined : columnRevealAnimation({
+ duration, appearFrames: fitted.appearFrames, moveFrames: fitted.moveFrames,
+ finalCenterX, finalCenterY, stageCenterX, stageCenterY, entryCenterY,
+ stageSize: style.stageSizePx, finalSize: contentSize, easing: style.motion.easing,
+ });
+ presents.push(present({
+ id: `${program.id}:item:${item.id}:stage`, start: entry.active.startFrame, end: entry.active.endFrameExclusive,
+ stacking: item.stackingOrder ?? style.stageStackingOrder,
+ tieBreak: `${program.id}:item:${String(item.rank).padStart(4, "0")}:${item.id}:stage`, elements: itemElements(rootAnimation),
+ }));
+ }
if (entry.settled.endFrameExclusive > entry.settled.startFrame) presents.push(present({
id: `${program.id}:item:${item.id}:settled`, start: entry.settled.startFrame, end: entry.settled.endFrameExclusive,
stacking: item.stackingOrder ?? style.itemStackingOrder,
- tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:settled`, elements: itemElements(),
+ tieBreak: `${program.id}:item:${String(item.rank).padStart(4, "0")}:${item.id}:settled`, elements: itemElements(),
}));
}
return sealTrack(space, program.id, presents);
diff --git a/packages/ranking/src/schedule.ts b/packages/ranking/src/schedule.ts
index 8b2d7eca..1a38320f 100644
--- a/packages/ranking/src/schedule.ts
+++ b/packages/ranking/src/schedule.ts
@@ -4,6 +4,7 @@ import {
} from "@hypit/media";
import type { SynchronizedMedia } from "@hypit/media";
import type {
+ NarrativeExcerpt,
NarrativeMomentRef,
NarrativeSelectionRef,
} from "@hypit/narrative";
@@ -16,10 +17,13 @@ import { canonicalize, isDigest } from "@hypit/protocol";
import { verifyText } from "@hypit/text";
import type { Text } from "@hypit/text";
import type { CompleteSemanticMap } from "@hypit/semantic-map";
-import { assertSpatialFrame } from "@hypit/spatial";
+import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
+import type { CanvasSpace } from "@hypit/spatial";
import {
locateMomentOccurrences,
locateSelectionOccurrences,
+ projectSegmentWindow,
+ projectSelectionWindows,
resolveTriggeredSchedule,
} from "@hypit/temporal";
@@ -27,8 +31,11 @@ import type {
ColumnItem,
ColumnItemSet,
ColumnItemSpec,
+ ColumnOuterWindow,
ColumnProgram,
+ ColumnSchedule,
ColumnStyle,
+ ColumnWindowCandidateSet,
RankingBoardPaint,
RankingHeader,
RankingItemSpec,
@@ -42,6 +49,7 @@ import type {
RankingSoundStyle,
RankingTextStyle,
RankingVariant,
+ TriggeredRankingSchedule,
TierBoardItem,
TierBoardItemSet,
TierBoardItemSpec,
@@ -220,8 +228,9 @@ export function assertRankingItemSpec(value: RankingItemSpec): void {
assert(value.entry === "direct" || value.entry === "stage", `TierBoardItemSpec.${value.id}.entry is invalid.`);
} else if (value.variant === "column") {
assert(value.label.trim().length > 0, `ColumnItemSpec.${value.id}.label is empty.`);
+ integer(value.rank, `ColumnItemSpec.${value.id}.rank`, 1);
+ assert(typeof value.preset === "boolean", `ColumnItemSpec.${value.id}.preset is invalid.`);
} else {
- assert(value.variant === "top-three", "RankingItemSpec variant is invalid.");
assert(value.label.trim().length > 0, `TopThreeItemSpec.${value.id}.label is empty.`);
}
if (value.stackingOrder !== undefined) stacking(value.stackingOrder, `RankingItemSpec.${value.id}.stackingOrder`);
@@ -258,11 +267,16 @@ export function assertRankingItemSpecSet(value: RankingItemSpecSet): void {
assert(["tier-board", "column", "top-three"].includes(value.variant),
"RankingItemSpecSet.variant is invalid.");
const ids = new Set<string>();
+ const ranks = new Set<number>();
for (const item of value.items) {
assertRankingItemSpec(item);
assert(item.variant === value.variant, "RankingItemSpecSet mixes component variants.");
assert(!ids.has(item.id), `RankingItemSpecSet repeats ${item.id}.`);
ids.add(item.id);
+ if (item.variant === "column") {
+ assert(!ranks.has(item.rank), `RankingItemSpecSet repeats Column rank ${item.rank}.`);
+ ranks.add(item.rank);
+ }
}
}
@@ -283,10 +297,11 @@ export function buildRankingSchedule(input: {
readonly outer: NarrativeSelectionRef;
readonly triggers: NarrativeMomentRef;
readonly terminal: NarrativeMomentRef;
-}): RankingSchedule {
+}): TriggeredRankingSchedule {
assertRankingHeader(input.header);
assertRankingItemSpecSet(input.items);
assert(input.items.variant === input.header.variant, "Ranking schedule variant disagrees with its item set.");
+ assert(input.header.variant !== "column", "Column uses item-owned Selection windows, not the triggered Ranking schedule.");
assert(input.items.items.length > 0, "Ranking requires at least one Item.");
assertProgramSpaceIdentity(input.space);
const outer = locateSelectionOccurrences(input.map, input.outer, input.space);
@@ -313,7 +328,7 @@ export function buildRankingSchedule(input: {
settled: { startFrame: exclusive.endFrameExclusive, endFrameExclusive: resolved.outer.endFrameExclusive },
};
});
- const result: RankingSchedule = {
+ const result: TriggeredRankingSchedule = {
id: input.header.id,
variant: input.header.variant,
@@ -322,13 +337,170 @@ export function buildRankingSchedule(input: {
entries,
};
assertRankingSchedule(result, input.space);
- return canonicalize(result) as unknown as RankingSchedule;
+ return canonicalize(result) as unknown as TriggeredRankingSchedule;
+}
+
+export function projectColumnSelectionOuterWindow(
+ map: CompleteSemanticMap,
+ space: ProgramSpace,
+ selection: NarrativeSelectionRef,
+): ColumnOuterWindow {
+ const occurrence = projectSelectionWindows({
+ itemId: "column-outer", map, selection, space, expansion: { kind: "one" },
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ })[0]!;
+ return canonicalize({ span: { ...occurrence.span } }) as unknown as ColumnOuterWindow;
+}
+
+export function projectColumnSegmentOuterWindow(
+ map: CompleteSemanticMap,
+ space: ProgramSpace,
+ segment: NarrativeExcerpt,
+): ColumnOuterWindow {
+ const occurrence = projectSegmentWindow({
+ itemId: "column-outer", map, segment, space,
+ projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },
+ });
+ return canonicalize({ span: { ...occurrence.span } }) as unknown as ColumnOuterWindow;
}
-export function assertRankingSchedule(value: RankingSchedule, space?: ProgramSpace): void {
+export function createColumnWindowCandidateSet(): ColumnWindowCandidateSet {
+ return { entries: [] };
+}
+
+export function assertColumnWindowCandidateSet(value: ColumnWindowCandidateSet): void {
+ assert(Array.isArray(value.entries), "ColumnWindowCandidateSet.entries is invalid.");
+ const ids = new Set<string>();
+ for (const [index, entry] of value.entries.entries()) {
+ identity(entry.itemId, `ColumnWindowCandidateSet.entries.${index}.itemId`);
+ identity(entry.occurrenceId, `ColumnWindowCandidateSet.entries.${index}.occurrenceId`);
+ assert(!ids.has(entry.itemId), `ColumnWindowCandidateSet repeats ${entry.itemId}.`);
+ ids.add(entry.itemId);
+ frame(entry.preferred.startFrame, `ColumnWindowCandidateSet.entries.${index}.preferred.startFrame`);
+ frame(entry.preferred.endFrameExclusive, `ColumnWindowCandidateSet.entries.${index}.preferred.endFrameExclusive`);
+ assert(entry.preferred.endFrameExclusive > entry.preferred.startFrame,
+ `ColumnWindowCandidateSet.entries.${index}.preferred is empty.`);
+ }
+}
+
+export function appendColumnWindowCandidate(
+ set: ColumnWindowCandidateSet,
+ spec: ColumnItemSpec,
+ map: CompleteSemanticMap,
+ space: ProgramSpace,
+ selection: NarrativeSelectionRef,
+): ColumnWindowCandidateSet {
+ assertColumnWindowCandidateSet(set);
+ assertRankingItemSpec(spec);
+ assert(!spec.preset, `Preset Column Item ${spec.id} cannot consume a Selection window.`);
+ assert(!set.entries.some((entry) => entry.itemId === spec.id), `Column Item ${spec.id} already has a Selection window.`);
+ const occurrence = projectSelectionWindows({
+ itemId: spec.id, map, selection, space, expansion: { kind: "one" },
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ })[0]!;
+ const result: ColumnWindowCandidateSet = {
+ entries: [...set.entries, {
+ itemId: spec.id,
+ occurrenceId: occurrence.id,
+ preferred: { ...occurrence.span },
+ }].sort((left, right) => left.itemId.localeCompare(right.itemId)),
+ };
+ assertColumnWindowCandidateSet(result);
+ return canonicalize(result) as unknown as ColumnWindowCandidateSet;
+}
+
+function clampColumnCandidate(
+ preferred: { readonly startFrame: number; readonly endFrameExclusive: number },
+ outer: { readonly startFrame: number; readonly endFrameExclusive: number },
+): { readonly startFrame: number; readonly endFrameExclusive: number } {
+ const startFrame = Math.max(preferred.startFrame, outer.startFrame);
+ const endFrameExclusive = Math.min(preferred.endFrameExclusive, outer.endFrameExclusive);
+ if (endFrameExclusive > startFrame) return { startFrame, endFrameExclusive };
+ if (preferred.endFrameExclusive <= outer.startFrame) {
+ return { startFrame: outer.startFrame, endFrameExclusive: outer.startFrame + 1 };
+ }
+ return { startFrame: outer.endFrameExclusive - 1, endFrameExclusive: outer.endFrameExclusive };
+}
+
+function resolveColumnActiveWindows(
+ candidates: readonly ColumnWindowCandidateSet["entries"][number][],
+ outer: { readonly startFrame: number; readonly endFrameExclusive: number },
+): ReadonlyMap<string, { readonly startFrame: number; readonly endFrameExclusive: number }> {
+ const capacity = outer.endFrameExclusive - outer.startFrame;
+ assert(capacity >= candidates.length,
+ `Column outer window has ${capacity} frames for ${candidates.length} non-preset Items.`);
+ const ordered = candidates.map((candidate) => ({
+ ...candidate,
+ clamped: clampColumnCandidate(candidate.preferred, outer),
+ })).sort((left, right) =>
+ left.clamped.startFrame - right.clamped.startFrame
+ || left.clamped.endFrameExclusive - right.clamped.endFrameExclusive
+ || left.occurrenceId.localeCompare(right.occurrenceId)
+ || left.itemId.localeCompare(right.itemId));
+ const resolved = new Map<string, { readonly startFrame: number; readonly endFrameExclusive: number }>();
+ let cursor = outer.startFrame;
+ for (const [index, candidate] of ordered.entries()) {
+ const remaining = ordered.length - index - 1;
+ const latestEnd = outer.endFrameExclusive - remaining;
+ const startFrame = Math.min(Math.max(candidate.clamped.startFrame, cursor), latestEnd - 1);
+ const endFrameExclusive = Math.min(Math.max(candidate.clamped.endFrameExclusive, startFrame + 1), latestEnd);
+ resolved.set(candidate.itemId, { startFrame, endFrameExclusive });
+ cursor = endFrameExclusive;
+ }
+ return resolved;
+}
+
+export function buildColumnSchedule(input: {
+ readonly header: RankingHeader;
+ readonly items: RankingItemSpecSet;
+ readonly outer: ColumnOuterWindow;
+ readonly candidates: ColumnWindowCandidateSet;
+}): ColumnSchedule {
+ assertRankingHeader(input.header);
+ assert(input.header.variant === "column", "Column Schedule requires a Column header.");
+ assertRankingItemSpecSet(input.items);
+ assert(input.items.variant === "column", "Column Schedule requires Column Items.");
+ assert(input.items.items.length > 0, "Column requires at least one Item.");
+ assertColumnWindowCandidateSet(input.candidates);
+ frame(input.outer.span.startFrame, "ColumnOuterWindow.span.startFrame");
+ frame(input.outer.span.endFrameExclusive, "ColumnOuterWindow.span.endFrameExclusive");
+ assert(input.outer.span.endFrameExclusive > input.outer.span.startFrame, "ColumnOuterWindow.span is empty.");
+ const items = [...input.items.items as readonly ColumnItemSpec[]]
+ .sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));
+ const expected = new Set(items.filter((item) => !item.preset).map((item) => item.id));
+ const received = new Set(input.candidates.entries.map((entry) => entry.itemId));
+ assert(expected.size === received.size && [...expected].every((id) => received.has(id)),
+ "Column non-preset Items and Selection windows differ.");
+ const active = resolveColumnActiveWindows(input.candidates.entries, input.outer.span);
+ const result: ColumnSchedule = {
+ id: input.header.id,
+ variant: "column",
+ outer: { ...input.outer.span },
+ entries: items.map((item) => {
+ if (item.preset) return {
+ itemId: item.id,
+ mode: "preset" as const,
+ settled: { ...input.outer.span },
+ };
+ const candidate = input.candidates.entries.find((entry) => entry.itemId === item.id)!;
+ const window = active.get(item.id)!;
+ return {
+ itemId: item.id,
+ mode: "reveal" as const,
+ preferred: { ...candidate.preferred },
+ active: { ...window },
+ settled: { startFrame: window.endFrameExclusive, endFrameExclusive: input.outer.span.endFrameExclusive },
+ };
+ }),
+ };
+ assertRankingSchedule(result);
+ return canonicalize(result) as unknown as ColumnSchedule;
+}
+
+function assertTriggeredRankingSchedule(value: TriggeredRankingSchedule): void {
identity(value.id, "RankingSchedule.id");
- assert(["tier-board", "column", "top-three"].includes(value.variant),
- "RankingSchedule.variant is invalid.");
+ assert(["tier-board", "top-three"].includes(value.variant),
+ "Triggered RankingSchedule.variant is invalid.");
frame(value.outer.startFrame, "RankingSchedule.outer.startFrame");
frame(value.outer.endFrameExclusive, "RankingSchedule.outer.endFrameExclusive");
assert(value.outer.endFrameExclusive > value.outer.startFrame, "RankingSchedule.outer is empty.");
@@ -357,6 +529,52 @@ export function assertRankingSchedule(value: RankingSchedule, space?: ProgramSpa
assert(value.entries[0]!.triggerFrame >= value.outer.startFrame, "RankingSchedule starts before its outer window.");
assert(value.entries.at(-1)!.stage.endFrameExclusive === value.terminalFrame,
"RankingSchedule final stage does not end at terminal.");
+}
+
+function assertColumnSchedule(value: ColumnSchedule): void {
+ identity(value.id, "ColumnSchedule.id");
+ frame(value.outer.startFrame, "ColumnSchedule.outer.startFrame");
+ frame(value.outer.endFrameExclusive, "ColumnSchedule.outer.endFrameExclusive");
+ assert(value.outer.endFrameExclusive > value.outer.startFrame, "ColumnSchedule.outer is empty.");
+ assert(value.entries.length > 0, "ColumnSchedule.entries is empty.");
+ const ids = new Set<string>();
+ const active: Array<{ readonly itemId: string; readonly startFrame: number; readonly endFrameExclusive: number }> = [];
+ for (const [index, entry] of value.entries.entries()) {
+ identity(entry.itemId, `ColumnSchedule.entries.${index}.itemId`);
+ assert(!ids.has(entry.itemId), `ColumnSchedule repeats ${entry.itemId}.`);
+ ids.add(entry.itemId);
+ if (entry.mode === "preset") {
+ assert(entry.settled.startFrame === value.outer.startFrame
+ && entry.settled.endFrameExclusive === value.outer.endFrameExclusive,
+ `ColumnSchedule preset ${entry.itemId} does not occupy the outer window.`);
+ continue;
+ }
+ frame(entry.preferred.startFrame, `ColumnSchedule.entries.${index}.preferred.startFrame`);
+ frame(entry.preferred.endFrameExclusive, `ColumnSchedule.entries.${index}.preferred.endFrameExclusive`);
+ assert(entry.preferred.endFrameExclusive > entry.preferred.startFrame,
+ `ColumnSchedule.entries.${index}.preferred is empty.`);
+ frame(entry.active.startFrame, `ColumnSchedule.entries.${index}.active.startFrame`);
+ frame(entry.active.endFrameExclusive, `ColumnSchedule.entries.${index}.active.endFrameExclusive`);
+ assert(entry.active.startFrame >= value.outer.startFrame
+ && entry.active.endFrameExclusive <= value.outer.endFrameExclusive
+ && entry.active.endFrameExclusive > entry.active.startFrame,
+ `ColumnSchedule.entries.${index}.active is outside the outer window.`);
+ assert(entry.settled.startFrame === entry.active.endFrameExclusive
+ && entry.settled.endFrameExclusive === value.outer.endFrameExclusive,
+ `ColumnSchedule.entries.${index}.settled is inconsistent.`);
+ active.push({ itemId: entry.itemId, ...entry.active });
+ }
+ active.sort((left, right) => left.startFrame - right.startFrame
+ || left.endFrameExclusive - right.endFrameExclusive || left.itemId.localeCompare(right.itemId));
+ for (let index = 1; index < active.length; index += 1) {
+ assert(active[index]!.startFrame >= active[index - 1]!.endFrameExclusive,
+ `ColumnSchedule active windows ${active[index - 1]!.itemId} and ${active[index]!.itemId} overlap.`);
+ }
+}
+
+export function assertRankingSchedule(value: RankingSchedule, space?: ProgramSpace): void {
+ if (value.variant === "column") assertColumnSchedule(value);
+ else assertTriggeredRankingSchedule(value);
if (space !== undefined) {
assertProgramSpaceIdentity(space);
assert(value.outer.endFrameExclusive <= programSpaceFrameCount(space), "RankingSchedule exceeds ProgramSpace.");
@@ -399,13 +617,20 @@ export function appendTopThreeItem(set: TopThreeItemSet, spec: TopThreeItemSpec,
return canonicalize({ ...set, items: [...set.items, { ...structuredClone(spec), ...(icon === undefined ? {} : { icon: structuredClone(icon) }) }] }) as unknown as TopThreeItemSet;
}
-function idsEqual(schedule: RankingSchedule, items: readonly { readonly id: string }[]): void {
+function idsEqual(schedule: TriggeredRankingSchedule, items: readonly { readonly id: string }[]): void {
assert(schedule.entries.length === items.length, "Ranking Program item count differs from its Schedule.");
for (const [index, item] of items.entries()) {
assert(schedule.entries[index]?.itemId === item.id, "Ranking Program item order differs from its Schedule.");
}
}
+function columnIdsEqual(schedule: ColumnSchedule, items: readonly { readonly id: string }[]): void {
+ assert(schedule.entries.length === items.length, "Column Program item count differs from its Schedule.");
+ const scheduled = new Set(schedule.entries.map((entry) => entry.itemId));
+ assert(scheduled.size === items.length && items.every((item) => scheduled.has(item.id)),
+ "Column Program Items differ from its Schedule.");
+}
+
export function fitRankingStageMotion(
durationFrames: number,
preferredAppearFrames: number,
@@ -418,6 +643,24 @@ export function fitRankingStageMotion(
return { appearFrames: Math.min(preferredAppearFrames, durationFrames - moveFrames), moveFrames };
}
+export function fitColumnRevealMotion(
+ durationFrames: number,
+ preferredAppearFrames: number,
+ preferredMoveFrames: number,
+): { readonly mode: "direct" } | { readonly mode: "stage"; readonly appearFrames: number; readonly moveFrames: number } {
+ assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "Column reveal duration is invalid.");
+ assert(Number.isSafeInteger(preferredAppearFrames) && preferredAppearFrames > 0, "Column appear duration is invalid.");
+ assert(Number.isSafeInteger(preferredMoveFrames) && preferredMoveFrames > 0, "Column move duration is invalid.");
+ if (durationFrames === 1) return { mode: "direct" };
+ const preferredTotal = preferredAppearFrames + preferredMoveFrames;
+ if (durationFrames >= preferredTotal) {
+ return { mode: "stage", appearFrames: preferredAppearFrames, moveFrames: preferredMoveFrames };
+ }
+ const appearFrames = Math.min(durationFrames - 1,
+ Math.max(1, Math.round(durationFrames * preferredAppearFrames / preferredTotal)));
+ return { mode: "stage", appearFrames, moveFrames: durationFrames - appearFrames };
+}
+
export function buildTierBoardProgram(header: RankingHeader, frameValue: import("@hypit/spatial").SpatialFrame, schedule: RankingSchedule, style: TierBoardStyle, set: TierBoardItemSet): TierBoardProgram {
assert(header.variant === "tier-board" && schedule.variant === "tier-board", "TierBoard variant is inconsistent.");
assertSpatialFrame(frameValue);
@@ -430,12 +673,14 @@ export function buildTierBoardProgram(header: RankingHeader, frameValue: import(
return canonicalize(result) as unknown as TierBoardProgram;
}
-export function buildColumnProgram(header: RankingHeader, frameValue: import("@hypit/spatial").SpatialFrame, schedule: RankingSchedule, style: ColumnStyle, set: ColumnItemSet): ColumnProgram {
+export function buildColumnProgram(header: RankingHeader, canvasValue: CanvasSpace, frameValue: import("@hypit/spatial").SpatialFrame, schedule: RankingSchedule, style: ColumnStyle, set: ColumnItemSet): ColumnProgram {
assert(header.variant === "column" && schedule.variant === "column", "Column variant is inconsistent.");
+ assertCanvasSpace(canvasValue);
assertSpatialFrame(frameValue);
assertColumnStyle(style);
- idsEqual(schedule, set.items);
- const result: ColumnProgram = { id: header.id, frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items: structuredClone(set.items) };
+ columnIdsEqual(schedule, set.items);
+ const items = [...set.items].map((item) => structuredClone(item)).sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));
+ const result: ColumnProgram = { id: header.id, canvas: structuredClone(canvasValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };
assertColumnProgram(result);
return canonicalize(result) as unknown as ColumnProgram;
}
@@ -463,10 +708,14 @@ export function assertTierBoardProgram(value: TierBoardProgram): void {
export function assertColumnProgram(value: ColumnProgram): void {
assertRankingSchedule(value.schedule);
assert(value.schedule.variant === "column", "ColumnProgram Schedule variant is invalid.");
+ assertCanvasSpace(value.canvas);
assertSpatialFrame(value.frame);
assertColumnStyle(value.style);
- idsEqual(value.schedule, value.items);
+ columnIdsEqual(value.schedule, value.items);
value.items.forEach((item) => { assertRankingItemSpec(item); if (item.icon !== undefined) assertBlobImage(item.icon, `ColumnItem.${item.id}.icon`); });
+ for (let index = 1; index < value.items.length; index += 1) {
+ assert(value.items[index - 1]!.rank < value.items[index]!.rank, "ColumnProgram Items are not ordered by unique rank.");
+ }
}
export function assertTopThreeProgram(value: TopThreeProgram): void {
@@ -506,13 +755,16 @@ export function buildTierBoardSoundEvents(schedule: RankingSchedule, style: Tier
export function buildColumnSoundEvents(schedule: RankingSchedule, style: ColumnStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
assert(schedule.variant === "column" && specs.variant === "column", "Column event inputs disagree.");
assertColumnStyle(style);
- idsEqual(schedule, specs.items);
- return sealEvents(schedule.id, schedule.variant, schedule.entries.flatMap((entry) => {
- const duration = entry.stage.endFrameExclusive - entry.triggerFrame;
- const fitted = fitRankingStageMotion(duration, style.motion.appearFrames, style.motion.moveFrames, true);
- return [event(schedule.id, entry.itemId, "appear", entry.triggerFrame),
- event(schedule.id, entry.itemId, "move", entry.stage.endFrameExclusive - fitted.moveFrames)];
- }));
+ columnIdsEqual(schedule, specs.items);
+ const events = schedule.entries.flatMap((entry) => {
+ if (entry.mode === "preset") return [];
+ const duration = entry.active.endFrameExclusive - entry.active.startFrame;
+ const fitted = fitColumnRevealMotion(duration, style.motion.appearFrames, style.motion.moveFrames);
+ return [event(schedule.id, entry.itemId, "appear", entry.active.startFrame),
+ ...(fitted.mode === "direct" ? []
+ : [event(schedule.id, entry.itemId, "move", entry.active.endFrameExclusive - fitted.moveFrames)])];
+ }).sort((left, right) => left.frame - right.frame || left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id));
+ return sealEvents(schedule.id, schedule.variant, events);
}
export function buildTopThreeSoundEvents(schedule: RankingSchedule, style: TopThreeStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
diff --git a/packages/ranking/src/style.ts b/packages/ranking/src/style.ts
index 5a071ddd..7b16b56d 100644
--- a/packages/ranking/src/style.ts
+++ b/packages/ranking/src/style.ts
@@ -205,8 +205,8 @@ export function decodeColumnStyle(
iconSizePx: number(recipe, "icon-size", 58),
iconRadiusPx: number(recipe, "icon-radius", 10),
iconFit: oneOf(recipe, "icon-fit", ["contain", "cover"] as const, "cover"),
- stagePoint: { x: number(recipe, "stage-x", 0.5), y: number(recipe, "stage-y", 0.24) },
- stageSizePx: number(recipe, "stage-size", 132),
+ stagePoint: { x: number(recipe, "stage-x", 0.66), y: number(recipe, "stage-y", 0.73) },
+ stageSizePx: number(recipe, "stage-size", 356),
motion: motion(recipe),
boardStackingOrder: integer(recipe, "board-stack", 20),
stageStackingOrder: integer(recipe, "stage-stack", 25),
diff --git a/packages/ranking/src/surface.ts b/packages/ranking/src/surface.ts
index b2dbe6bf..7f90f145 100644
--- a/packages/ranking/src/surface.ts
+++ b/packages/ranking/src/surface.ts
@@ -1,20 +1,25 @@
+import {
+ assertEmptyElement as empty,
+ assertAttributes as allowed,
+ localName,
+ textAttribute as text,
+ optionalTextAttribute as optionalText,
+ type StructuredElement,
+ type StructuredSurfaceHandler,
+ type SurfaceRecordDraft,
+ type SurfaceResolvedReference,
+ type MarkupAttributeValue,
+} from "@hypit/markup";
+import { sameType, type CanonicalValue, type TypeRef } from "@hypit/protocol";
import { mediaTypes } from "@hypit/media";
import type { FontArtifactRef, FontStackRef } from "@hypit/media";
import { narrativeTypes } from "@hypit/narrative";
import { programSpaceTypes } from "@hypit/program-space";
-import type { CanonicalValue, TypeRef } from "@hypit/protocol";
import { semanticMapTypes } from "@hypit/semantic-map";
import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import type { SvsRecipe } from "@hypit/svs";
import { textTypes } from "@hypit/text";
-import type {
- StructuredElement,
- StructuredSurfaceHandler,
- SurfaceRecordDraft,
- SurfaceResolvedReference,
- MarkupAttributeValue,
-} from "@hypit/markup";
import { createRankingFragment } from "./fragment.js";
import type { RankingFragmentItem, RankingFragmentSound } from "./fragment.js";
@@ -39,38 +44,6 @@ import type {
TopThreeItemSpec,
} from "./types.js";
-function sameType(left: TypeRef, right: TypeRef): boolean {
- return left.module.name === right.module.name
- && left.module.version === right.module.version
- && left.name === right.name;
-}
-
-function allowed(element: StructuredElement, names: readonly string[]): void {
- const permit = new Set(names);
- const unknown = Object.keys(element.attributes).filter((name) => !permit.has(name));
- if (unknown.length > 0) throw new Error(`${element.name} has unsupported attributes ${unknown.join(", ")}.`);
-}
-
-function empty(element: StructuredElement): void {
- if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
- throw new Error(`${element.name} must be empty.`);
- }
-}
-
-function text(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();
-}
-
-function optionalText(element: StructuredElement, name: string): string | undefined {
- const value = element.attributes[name];
- if (value === undefined) return undefined;
- if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
- return value.trim();
-}
-
function integer(element: StructuredElement, name: string): number | undefined {
const source = optionalText(element, name);
if (source === undefined) return undefined;
@@ -79,6 +52,14 @@ function integer(element: StructuredElement, name: string): number | undefined {
return value;
}
+function boolean(element: StructuredElement, name: string, fallback: boolean): boolean {
+ const source = optionalText(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.`);
+}
+
function reference(
raw: MarkupAttributeValue | undefined,
label: string,
@@ -132,11 +113,6 @@ function styleSurface<T>(
export const decodeTierBoardStyleSurface = styleSurface(rankingTypes.tierStyle, decodeTierBoardStyle);
export const decodeColumnStyleSurface = styleSurface(rankingTypes.columnStyle, decodeColumnStyle);
export const decodeTopThreeStyleSurface = styleSurface(rankingTypes.topThreeStyle, decodeTopThreeStyle);
-
-function localName(element: StructuredElement): string {
- return element.name.slice(element.name.lastIndexOf(":") + 1);
-}
-
function textValue(
raw: MarkupAttributeValue | undefined,
label: string,
@@ -147,7 +123,7 @@ function textValue(
}
function itemIdentity(element: StructuredElement, suffix: string): string {
- return optionalText(element, "id") ?? `${localName(element).replace(/Item$/u, "").toLowerCase()}-${suffix}`;
+ return optionalText(element, "id") ?? `${localName(element.name).replace(/Item$/u, "").toLowerCase()}-${suffix}`;
}
function itemSpec(
@@ -155,7 +131,7 @@ function itemSpec(
variant: RankingVariant,
suffix: string,
resolve: (path: string) => SurfaceResolvedReference | undefined,
-): { readonly spec: RankingItemSpec | RankingTextItemShell; readonly content?: SurfaceResolvedReference } {
+): { readonly spec: RankingItemSpec | RankingTextItemShell; readonly content?: SurfaceResolvedReference; readonly timing?: SurfaceResolvedReference } {
const id = itemIdentity(element, suffix);
const stackingOrder = integer(element, "stack");
let value: RankingItemSpec;
@@ -168,18 +144,41 @@ function itemSpec(
variant, id, tier: text(element, "tier"), entry,
...(stackingOrder === undefined ? {} : { stackingOrder }),
} satisfies TierBoardItemSpec;
- } else if (variant === "column" || variant === "top-three") {
+ assertRankingItemSpec(value);
+ return { spec: value };
+ } else if (variant === "column") {
+ allowed(element, ["id", "label", "icon", "rank", "preset", "during", "stack"]);
+ empty(element);
+ const rank = integer(element, "rank");
+ if (rank === undefined || rank < 1) throw new Error(`${element.name}.rank must be a positive integer.`);
+ const preset = boolean(element, "preset", false);
+ const timing = element.attributes.during === undefined ? undefined
+ : reference(element.attributes.during, `${element.name}.during`, narrativeTypes.selection, resolve);
+ if (preset && timing !== undefined) throw new Error(`${element.name} cannot combine preset=true with during.`);
+ if (!preset && timing === undefined) throw new Error(`${element.name} requires during unless preset=true.`);
+ const label = textValue(element.attributes.label, `${element.name}.label`, resolve);
+ if (typeof label === "string") value = {
+ variant, id, label, rank, preset,
+ ...(stackingOrder === undefined ? {} : { stackingOrder }),
+ } satisfies ColumnItemSpec;
+ else return { spec: sealRankingTextItemShell({
+ variant, id, rank, preset,
+ ...(stackingOrder === undefined ? {} : { stackingOrder }),
+ }), content: label, ...(timing === undefined ? {} : { timing }) };
+ assertRankingItemSpec(value);
+ return { spec: value, ...(timing === undefined ? {} : { timing }) };
+ } else if (variant === "top-three") {
allowed(element, ["id", "label", "icon", "stack"]);
empty(element);
const label = textValue(element.attributes.label, `${element.name}.label`, resolve);
- if (typeof label !== "string") return { spec: sealRankingTextItemShell({
+ if (typeof label === "string") value = {
+ variant, id, label,
+ ...(stackingOrder === undefined ? {} : { stackingOrder }),
+ } satisfies TopThreeItemSpec;
+ else return { spec: sealRankingTextItemShell({
variant, id,
...(stackingOrder === undefined ? {} : { stackingOrder }),
}), content: label };
- value = {
- variant, id, label,
- ...(stackingOrder === undefined ? {} : { stackingOrder }),
- } satisfies ColumnItemSpec | TopThreeItemSpec;
} else throw new Error(`${element.name} belongs to an unknown Ranking variant.`);
assertRankingItemSpec(value);
return { spec: value };
@@ -193,15 +192,26 @@ const variantDefinition = {
function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
return ({ element, resolveReference }) => {
- allowed(element, ["id", "map", "space", "frame", "during", "triggers", "terminal", "style", "appear-sound", "move-sound"]);
+ const common = ["id", "map", "space", "frame", "during", "triggers", "terminal", "style", "appear-sound", "move-sound"];
+ const attributes = variant === "column"
+ ? [...common.filter((name) => name !== "triggers" && name !== "terminal"), "canvas"]
+ : common;
+ allowed(element, attributes);
const id = text(element, "id");
const selected = variantDefinition[variant];
const map = reference(element.attributes.map, `${element.name}.map`, semanticMapTypes.complete, resolveReference);
const space = reference(element.attributes.space, `${element.name}.space`, programSpaceTypes.programSpace, resolveReference);
+ const canvas = variant === "column"
+ ? reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference)
+ : undefined;
const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);
- const outer = reference(element.attributes.during, `${element.name}.during`, narrativeTypes.selection, resolveReference);
- const triggers = reference(element.attributes.triggers, `${element.name}.triggers`, narrativeTypes.moment, resolveReference);
- const terminal = reference(element.attributes.terminal, `${element.name}.terminal`, narrativeTypes.moment, resolveReference);
+ const outer = variant === "column"
+ ? oneOfReference(element.attributes.during, `${element.name}.during`, [narrativeTypes.selection, narrativeTypes.excerpt], resolveReference)
+ : reference(element.attributes.during, `${element.name}.during`, narrativeTypes.selection, resolveReference);
+ const triggers = variant === "column" ? undefined
+ : reference(element.attributes.triggers, `${element.name}.triggers`, narrativeTypes.moment, resolveReference);
+ const terminal = variant === "column" ? undefined
+ : reference(element.attributes.terminal, `${element.name}.terminal`, narrativeTypes.moment, resolveReference);
const styleRaw = element.attributes.style;
const style = reference(styleRaw, `${element.name}.style`, selected.style, resolveReference);
const records: SurfaceRecordDraft[] = [];
@@ -213,7 +223,10 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
});
const inputs: Record<string, typeof map.ref> = {
header: { kind: "record", id: headerId }, map: map.ref, space: space.ref, frame: frame.ref,
- outer: outer.ref, triggers: triggers.ref, terminal: terminal.ref, style: style.ref,
+ outer: outer.ref, style: style.ref,
+ ...(canvas === undefined ? {} : { canvas: canvas.ref }),
+ ...(triggers === undefined ? {} : { triggers: triggers.ref }),
+ ...(terminal === undefined ? {} : { terminal: terminal.ref }),
};
const items: RankingFragmentItem[] = [];
const itemIds = new Set<string>();
@@ -224,7 +237,7 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
if (child.value.trim().length > 0) throw new Error(`${element.name} accepts ${selected.tag} children only.`);
continue;
}
- if (localName(child) !== selected.tag) throw new Error(`${element.name} accepts ${selected.tag} children only.`);
+ if (localName(child.name) !== selected.tag) throw new Error(`${element.name} accepts ${selected.tag} children only.`);
index += 1;
const suffix = String(index).padStart(4, "0");
const authored = itemSpec(child, variant, suffix, resolveReference);
@@ -238,13 +251,19 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
inputs[specName] = { kind: "record", id: specId };
const contentName = authored.content === undefined ? undefined : `item-${suffix}-content`;
if (authored.content !== undefined) inputs[contentName!] = authored.content.ref;
+ const timingName = authored.timing === undefined ? undefined : `item-${suffix}-timing`;
+ if (authored.timing !== undefined) inputs[timingName!] = authored.timing.ref;
let iconName: string | undefined;
if (variant === "tier-board" || child.attributes.icon !== undefined) {
const icon = reference(child.attributes.icon, `${child.name}.icon`, mediaTypes.blobArtifact, resolveReference);
iconName = `item-${suffix}-icon`;
inputs[iconName] = icon.ref;
}
- items.push({ suffix, specName, ...(contentName === undefined ? {} : { contentName }), ...(iconName === undefined ? {} : { iconName }) });
+ items.push({ suffix, specName,
+ ...(contentName === undefined ? {} : { contentName }),
+ ...(iconName === undefined ? {} : { iconName }),
+ ...(timingName === undefined ? {} : { timingName }),
+ });
}
if (items.length === 0) throw new Error(`${element.name} requires at least one ${selected.tag}.`);
const sound: RankingFragmentSound = {
@@ -265,7 +284,8 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
}
inputs["sound-style"] = soundStyle.ref;
}
- const fragment = createRankingFragment(variant, items, sound);
+ const outerKind = sameType(outer.type, narrativeTypes.excerpt) ? "segment" : "selection";
+ const fragment = createRankingFragment(variant, items, sound, outerKind);
return {
records,
components: [{
diff --git a/packages/ranking/src/types.ts b/packages/ranking/src/types.ts
index f63ddf66..e22d1280 100644
--- a/packages/ranking/src/types.ts
+++ b/packages/ranking/src/types.ts
@@ -4,7 +4,7 @@ import type {
SynchronizedMedia,
} from "@hypit/media";
import type { BlobRef } from "@hypit/protocol";
-import type { SpatialFrame } from "@hypit/spatial";
+import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
export type RankingVariant = "tier-board" | "column" | "top-three";
@@ -13,7 +13,7 @@ export type RankingHeader = {
readonly variant: RankingVariant;
};
-export type RankingScheduleEntry = {
+export type TriggeredRankingScheduleEntry = {
readonly itemId: string;
readonly triggerFrame: number;
readonly stage: FrameSpan;
@@ -21,14 +21,51 @@ export type RankingScheduleEntry = {
readonly settled: FrameSpan;
};
-export type RankingSchedule = {
+export type TriggeredRankingSchedule = {
readonly id: string;
- readonly variant: RankingVariant;
+ readonly variant: Exclude<RankingVariant, "column">;
readonly outer: FrameSpan;
readonly terminalFrame: number;
- readonly entries: readonly RankingScheduleEntry[];
+ readonly entries: readonly TriggeredRankingScheduleEntry[];
+};
+
+export type ColumnOuterWindow = {
+ readonly span: FrameSpan;
+};
+
+export type ColumnWindowCandidate = {
+ readonly itemId: string;
+ readonly occurrenceId: string;
+ readonly preferred: FrameSpan;
+};
+
+export type ColumnWindowCandidateSet = {
+ readonly entries: readonly ColumnWindowCandidate[];
};
+export type ColumnScheduleEntry =
+ | {
+ readonly itemId: string;
+ readonly mode: "preset";
+ readonly settled: FrameSpan;
+ }
+ | {
+ readonly itemId: string;
+ readonly mode: "reveal";
+ readonly preferred: FrameSpan;
+ readonly active: FrameSpan;
+ readonly settled: FrameSpan;
+ };
+
+export type ColumnSchedule = {
+ readonly id: string;
+ readonly variant: "column";
+ readonly outer: FrameSpan;
+ readonly entries: readonly ColumnScheduleEntry[];
+};
+
+export type RankingSchedule = TriggeredRankingSchedule | ColumnSchedule;
+
export type RankingTextStyle = {
readonly fonts: readonly FontArtifactRef[];
readonly sizePx: number;
@@ -135,6 +172,8 @@ export type ColumnItemSpec = {
readonly variant: "column";
readonly id: string;
readonly label: string;
+ readonly rank: number;
+ readonly preset: boolean;
readonly stackingOrder?: number;
};
@@ -174,21 +213,22 @@ export type TopThreeItemSet = {
export type TierBoardProgram = {
readonly id: string;
readonly frame: SpatialFrame;
- readonly schedule: RankingSchedule;
+ readonly schedule: TriggeredRankingSchedule;
readonly style: TierBoardStyle;
readonly items: readonly TierBoardItem[];
};
export type ColumnProgram = {
readonly id: string;
+ readonly canvas: CanvasSpace;
readonly frame: SpatialFrame;
- readonly schedule: RankingSchedule;
+ readonly schedule: ColumnSchedule;
readonly style: ColumnStyle;
readonly items: readonly ColumnItem[];
};
export type TopThreeProgram = {
readonly id: string;
readonly frame: SpatialFrame;
- readonly schedule: RankingSchedule;
+ readonly schedule: TriggeredRankingSchedule;
readonly style: TopThreeStyle;
readonly items: readonly TopThreeItem[];
};
diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.ts
index bf209641..548dd3d2 100644
--- a/packages/ranking/test/ranking.test.ts
+++ b/packages/ranking/test/ranking.test.ts
@@ -6,19 +6,21 @@ import { fixtureDigest } from "../../../test/fixture-digest.js";
import { createResolvedClosure } from "@hypit/core";
import type { FontArtifactRef, SynchronizedMedia } from "@hypit/media";
import { mediaTypes } from "@hypit/media";
-import type { NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
+import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
import { sealProgramSpace } from "@hypit/program-space";
import type { CompleteSemanticMap } from "@hypit/semantic-map";
-import { sealSpatialFrame } from "@hypit/spatial";
+import { sealCanvasSpace, sealSpatialFrame } from "@hypit/spatial";
import type { SvsRecipe } from "@hypit/svs";
import {
appendColumnItem,
+ appendColumnWindowCandidate,
appendRankingItemSpec,
appendRankingSound,
appendTierBoardItem,
appendTopThreeItem,
buildColumnProgram,
+ buildColumnSchedule,
buildColumnSoundEvents,
buildRankingSchedule,
buildTierBoardProgram,
@@ -26,6 +28,7 @@ import {
buildTopThreeProgram,
buildTopThreeSoundEvents,
createColumnItemSet,
+ createColumnWindowCandidateSet,
createRankingItemSpecSet,
createRankingSoundSet,
createTierBoardItemSet,
@@ -48,13 +51,15 @@ import {
rankingMarkupSurfaces,
rankingProducers,
rankingTypes,
+ projectColumnSegmentOuterWindow,
sealRankingHeader,
} from "@hypit/ranking";
import type {
ColumnItemSpec,
+ ColumnSchedule,
RankingHeader,
RankingItemSpec,
- RankingSchedule,
+ TriggeredRankingSchedule,
TierBoardItemSpec,
TopThreeItemSpec,
} from "@hypit/ranking";
@@ -75,6 +80,10 @@ const space = sealProgramSpace({
durationSec: 8,
frameRate: { numerator: 30, denominator: 1 },
});
+const canvas = sealCanvasSpace({
+ widthPx: 1080, heightPx: 1920,
+ origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
+});
const frame = sealSpatialFrame({
xPx: 40, yPx: 80, widthPx: 720, heightPx: 560,
});
@@ -82,12 +91,20 @@ const map: CompleteSemanticMap = {
tokens: [],
anchors: [
{ identity: "outer-start", frame: 10 },
+ { identity: "segment:ranking:start", frame: 10 },
+ { identity: "early-start", frame: 25 },
{ identity: "one", frame: 30 },
+ { identity: "early-end", frame: 65 },
+ { identity: "overlap-start", frame: 55 },
{ identity: "two", frame: 70 },
+ { identity: "overlap-end", frame: 95 },
{ identity: "three", frame: 110 },
+ { identity: "late-start", frame: 120 },
{ identity: "four", frame: 150 },
+ { identity: "late-end", frame: 160 },
{ identity: "terminal", frame: 190 },
{ identity: "outer-end", frame: 230 },
+ { identity: "segment:ranking:end", frame: 230 },
],
};
const outer: NarrativeSelectionRef = {
@@ -98,6 +115,13 @@ const terminal: NarrativeMomentRef = {
id: "ranking-complete",
occurrences: [{ occurrence: 0, anchorId: "terminal" }],
};
+const rankingSegment: NarrativeExcerpt = { kind: "segment", id: "ranking", tokenStart: 0, tokenEndExclusive: 1 };
+const selection = (id: string, startAnchorId: string, endAnchorId: string): NarrativeSelectionRef => ({
+ id, occurrences: [{ occurrence: 0, startAnchorId, endAnchorId }],
+});
+const early = selection("early", "early-start", "early-end");
+const overlapping = selection("overlapping", "overlap-start", "overlap-end");
+const late = selection("late", "late-start", "late-end");
const triggers = (count: number): NarrativeMomentRef => ({
id: "next-rank",
occurrences: ["one", "two", "three", "four"].slice(0, count)
@@ -122,7 +146,7 @@ function specs(headerValue: RankingHeader, values: readonly RankingItemSpec[]) {
return set;
}
-function schedule(headerValue: RankingHeader, values: readonly RankingItemSpec[]): RankingSchedule {
+function schedule(headerValue: RankingHeader, values: readonly RankingItemSpec[]): TriggeredRankingSchedule {
return buildRankingSchedule({
header: headerValue, items: specs(headerValue, values), map, space, outer,
triggers: triggers(values.length), terminal,
@@ -132,16 +156,32 @@ function schedule(headerValue: RankingHeader, values: readonly RankingItemSpec[]
const tierSpec = (id: string, tier: string, entry: "direct" | "stage" = "direct"): TierBoardItemSpec => ({
variant: "tier-board", id, tier, entry,
});
-const columnSpec = (id: string): ColumnItemSpec => ({
- variant: "column", id, label: id.toUpperCase(),
+const columnSpec = (id: string, rank: number, preset = false): ColumnItemSpec => ({
+ variant: "column", id, label: id.toUpperCase(), rank, preset,
});
const topSpec = (id: string): TopThreeItemSpec => ({
variant: "top-three", id, label: id.toUpperCase(),
});
+function columnSchedule(
+ owner: RankingHeader,
+ values: readonly ColumnItemSpec[],
+ windows: Readonly<Record<string, NarrativeSelectionRef>>,
+ outerWindow = projectColumnSegmentOuterWindow(map, space, rankingSegment),
+): ColumnSchedule {
+ let candidates = createColumnWindowCandidateSet();
+ for (const value of values) {
+ if (value.preset) continue;
+ const timing = windows[value.id];
+ if (timing === undefined) throw new Error(`Missing test Selection for ${value.id}.`);
+ candidates = appendColumnWindowCandidate(candidates, value, map, space, timing);
+ }
+ return buildColumnSchedule({ header: owner, items: specs(owner, values), outer: outerWindow, candidates });
+}
+
test("RankingSchedule zips authored item and Moment order and preserves a settled suffix", () => {
- const owner = header("column", "tools");
- const value = schedule(owner, [columnSpec("fourth"), columnSpec("third"), columnSpec("second")]);
+ const owner = header("top-three", "tools");
+ const value = schedule(owner, [topSpec("fourth"), topSpec("third"), topSpec("second")]);
assert.deepEqual(value.entries.map((entry) => [entry.itemId, entry.stage, entry.cumulative]), [
["fourth", { startFrame: 30, endFrameExclusive: 70 }, { startFrame: 30, endFrameExclusive: 230 }],
["third", { startFrame: 70, endFrameExclusive: 110 }, { startFrame: 70, endFrameExclusive: 230 }],
@@ -151,8 +191,8 @@ test("RankingSchedule zips authored item and Moment order and preserves a settle
});
test("RankingSchedule rejects cardinality, outer/terminal ambiguity and authored physical reversal", () => {
- const owner = header("column");
- const values = [columnSpec("a"), columnSpec("b")];
+ const owner = header("tier-board");
+ const values = [tierSpec("a", "s"), tierSpec("b", "a")];
assert.throws(() => buildRankingSchedule({
header: owner, items: specs(owner, values), map, space, outer, triggers: triggers(1), terminal,
}), /cardinality/u);
@@ -197,22 +237,46 @@ test("TierBoard owns cumulative direct/stage placement and rejects invalid sched
}), /outside|strictly increasing/u);
});
-test("Column has one active stage, cumulative settled rows and truly optional icons", () => {
+test("Column projects a Segment outer, keeps rank independent from reveal time, presets rows and avoids overlaps", () => {
const owner = header("column", "column");
- const semantic = [columnSpec("one"), columnSpec("two"), columnSpec("three")];
+ const semantic = [
+ columnSpec("late-rank-one", 1),
+ columnSpec("preset-rank-three", 3, true),
+ columnSpec("early-rank-five", 5),
+ columnSpec("overlap-rank-two", 2),
+ ];
const style = decodeColumnStyle(recipe("ranking.column", { "appear-frames": 4, "move-frames": 6 }), font).style;
let set = createColumnItemSet();
set = appendColumnItem(set, semantic[0]!);
- set = appendColumnItem(set, semantic[1]!, image("two"));
+ set = appendColumnItem(set, semantic[1]!, image("preset"));
set = appendColumnItem(set, semantic[2]!);
- const value = schedule(owner, semantic);
- const program = buildColumnProgram(owner, frame, value, style, set);
+ set = appendColumnItem(set, semantic[3]!, image("overlap"));
+ const outerWindow = projectColumnSegmentOuterWindow(map, space, rankingSegment);
+ assert.deepEqual(outerWindow.span, { startFrame: 10, endFrameExclusive: 230 });
+ const value = columnSchedule(owner, semantic, {
+ "late-rank-one": late,
+ "early-rank-five": early,
+ "overlap-rank-two": overlapping,
+ }, outerWindow);
+ const program = buildColumnProgram(owner, canvas, frame, value, style, set);
const track = renderColumn(space, program);
- const items = track.presents.filter((item) => item.id.includes(":item:") && item.id.endsWith(":stage"));
- assert.deepEqual(items.map((item) => item.span.startFrame), [30, 70, 110]);
- assert.equal(items[0]?.elements.some((item) => item.kind === "image"), false);
- assert.equal(items[1]?.elements.some((item) => item.kind === "image"), true);
- assert.equal(value.entries.filter((entry) => entry.stage.startFrame <= 80 && 80 < entry.stage.endFrameExclusive).length, 1);
+ assert.deepEqual(program.items.map((item) => [item.id, item.rank]), [
+ ["late-rank-one", 1], ["overlap-rank-two", 2], ["preset-rank-three", 3], ["early-rank-five", 5],
+ ]);
+ const active = value.entries.filter((entry) => entry.mode === "reveal")
+ .map((entry) => [entry.itemId, entry.preferred, entry.active]);
+ assert.deepEqual(active, [
+ ["late-rank-one", { startFrame: 120, endFrameExclusive: 160 }, { startFrame: 120, endFrameExclusive: 160 }],
+ ["overlap-rank-two", { startFrame: 55, endFrameExclusive: 95 }, { startFrame: 65, endFrameExclusive: 95 }],
+ ["early-rank-five", { startFrame: 25, endFrameExclusive: 65 }, { startFrame: 25, endFrameExclusive: 65 }],
+ ]);
+ const preset = value.entries.find((entry) => entry.itemId === "preset-rank-three")!;
+ assert.deepEqual(preset, { itemId: "preset-rank-three", mode: "preset", settled: outerWindow.span });
+ const stages = track.presents.filter((item) => item.id.includes(":item:") && item.id.endsWith(":stage"));
+ assert.deepEqual(stages.map((item) => item.span.startFrame).sort((a, b) => a - b), [25, 65, 120]);
+ assert.equal(stages.find((item) => item.id.includes("overlap-rank-two"))?.elements.some((item) => item.kind === "image"), true);
+ assert.equal(track.presents.some((item) => item.id.endsWith(":item:preset-rank-three:stage")), false);
+ assert.equal(track.presents.find((item) => item.id.endsWith(":item:preset-rank-three:settled"))?.span.startFrame, 10);
});
test("TopThree accepts one to three optional-image Items and removes active accent in the settled suffix", () => {
@@ -246,20 +310,20 @@ const sound = (id: string): SynchronizedMedia => ({
test("visual and sound event plans share exact phase frames while absent sound stays an independent branch", () => {
const owner = header("column", "sound-column");
- const semantic = [columnSpec("one"), columnSpec("two")];
+ const semantic = [columnSpec("one", 7), columnSpec("two", 2)];
const decoded = decodeColumnStyle(recipe("ranking.column", {
"appear-frames": 4, "move-frames": 6, "appear-gain": 0.8, "move-gain": 0.6,
}), font);
- const value = schedule(owner, semantic);
+ const value = columnSchedule(owner, semantic, { one: early, two: overlapping });
const events = buildColumnSoundEvents(value, decoded.style, specs(owner, semantic));
assert.deepEqual(events.events.map((item) => [item.kind, item.frame]), [
- ["appear", 30], ["move", 64], ["appear", 70], ["move", 184],
+ ["appear", 25], ["move", 59], ["appear", 65], ["move", 89],
]);
let sounds = createRankingSoundSet();
sounds = appendRankingSound(sounds, "appear", sound("appear"));
sounds = appendRankingSound(sounds, "move", sound("move"));
const audio = renderRankingAudio(space, events, decoded.sound, sounds);
- assert.deepEqual(audio.clips.map((clip) => clip.target.startSample), [48_000, 102_400, 112_000, 294_400]);
+ assert.deepEqual(audio.clips.map((clip) => clip.target.startSample), [40_000, 94_400, 104_000, 142_400]);
assert.deepEqual(audio.clips.map((clip) => clip.gain), [0.8, 0.6, 0.8, 0.6]);
});
@@ -276,10 +340,10 @@ test("each component owns a distinct event law and repeated lowering is canonica
assert.deepEqual(buildTopThreeSoundEvents(schedule(topOwner, topItems), top, specs(topOwner, topItems)).events.map((item) => item.kind), ["appear"]);
const columnOwner = header("column", "deterministic");
- const columnItems = [columnSpec("one")];
+ const columnItems = [columnSpec("one", 3)];
const columnStyle = decodeColumnStyle(recipe("ranking.column"), font).style;
let set = appendColumnItem(createColumnItemSet(), columnItems[0]!);
- const program = buildColumnProgram(columnOwner, frame, schedule(columnOwner, columnItems), columnStyle, set);
+ const program = buildColumnProgram(columnOwner, canvas, frame, columnSchedule(columnOwner, columnItems, { one: early }), columnStyle, set);
assert.deepEqual(renderColumn(space, program), renderColumn(space, program));
});
@@ -296,8 +360,11 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image
const references = new Map<string, SurfaceResolvedReference>([
["map", plain("map", semanticMapTypes.complete)],
["space", plain("space", programSpaceTypes.programSpace)],
+ ["canvas", plain("canvas", spatialTypes.canvas)],
["frame", plain("frame", spatialTypes.frame)],
["outer", plain("outer", narrativeTypes.selection)],
+ ["ranking-segment", plain("ranking-segment", narrativeTypes.excerpt)],
+ ["column-reveal", plain("column-reveal", narrativeTypes.selection)],
["triggers", plain("triggers", narrativeTypes.moment)],
["terminal", plain("terminal", narrativeTypes.moment)],
["icon-1", plain("icon-1", mediaTypes.blobArtifact)],
@@ -332,10 +399,13 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image
triggers: ref("triggers"), terminal: ref("terminal"), style: ref("tier-style"),
}, [node("ranking:TierItem", { id: "tier-one", tier: "s", entry: "stage", icon: ref("icon-1") })])],
[decodeColumnSurface, node("ranking:Column", {
- id: "column", map: ref("map"), space: ref("space"), frame: ref("frame"), during: ref("outer"),
- triggers: ref("triggers"), terminal: ref("terminal"), style: ref("column-style"),
+ id: "column", map: ref("map"), space: ref("space"), canvas: ref("canvas"), frame: ref("frame"), during: ref("ranking-segment"),
+ style: ref("column-style"),
"appear-sound": ref("appear"), "move-sound": ref("move"),
- }, [node("ranking:ColumnItem", { id: "column-one", label: ref("copy") }), node("ranking:ColumnItem", { id: "column-two", label: "Two", icon: ref("icon-2") })])],
+ }, [
+ node("ranking:ColumnItem", { id: "column-one", rank: "1", label: ref("copy"), during: ref("column-reveal") }),
+ node("ranking:ColumnItem", { id: "column-two", rank: "5", preset: "true", label: "Two", icon: ref("icon-2") }),
+ ])],
[decodeTopThreeSurface, node("ranking:TopThree", {
id: "top", map: ref("map"), space: ref("space"), frame: ref("frame"), during: ref("outer"),
triggers: ref("triggers"), terminal: ref("terminal"), style: ref("top-style"),