Close the remaining gaps against the Astryx ai-chat template

[Astro-Han]

Status — 2026-08-03

Re-audited current main against the published Astryx 0.2.0 ai-chat template. Astryx 0.2.0 is also the current npm latest, so this comparison has no version drift.

Three of the original four slices are complete:

1. User-bubble geometry follows Astryx defaults — done in refactor(ui): drop the user-bubble overrides that fork Astryx defaults #1862.
2. Workbar resizing uses Astryx useResizable / ResizeHandle — done in refactor(ui): move workbar resizing onto Astryx Resizable #1863.
3. The composer uses ChatComposerInput, including trigger menus, inline draft tokens and paste-as-token — done in refactor(ui): move the composer onto ChatComposerInput #1865.

The issue now has one remaining in-scope slice. The artifact and chronology gaps found during the re-audit should be tracked separately rather than expanding this issue again.

Remaining: sent references and attachment hierarchy

The composer renders selected workspace files and Skills as Astryx ChatComposerTokens, but that structure exists only inside the editor. Submit serializes the draft to text, and the sent user bubble renders that text as a plain <span>.

Correction to the original issue: there is no shared persisted ChatComposerToken[] available for ChatTokenizedText to consume.

The two token kinds also have different authorities:

• /skill:<id> has one canonical grammar in @maka/core (SKILL_INVOCATION_TOKEN_SOURCE) and survives in displayText, so the transcript can derive it without adding a second persisted source of truth.
• @<workspace-path> is currently a prompt convention, not a canonical persisted reference grammar. Once serialized, it cannot always be distinguished from ordinary @text, especially when paths contain spaces. Exact round-tripping would require a real structured-reference contract, not a renderer regex.

Attachments are already structured AttachmentRefs and need no schema change. The current sent-message treatment places non-image file cards inside the user bubble; the Astryx template places compact Tokens above the bubble. Image thumbnails and quote chips are Maka product behavior and should remain.

Proposed close condition

• Valid /skill:<id> invocations render through ChatTokenizedText after send and after session reload, using the shared Core grammar.
• Non-image attachments render as a compact Astryx Token row above the user bubble.
• Image attachments keep thumbnail/lightbox behavior.
• Quotes keep their existing provenance chips.
• Ordinary @text is not guessed into a token.
• Workspace-file mentions remain plain after send until the product defines a durable structured-reference contract.
• Storybook covers a sent Skill invocation, mixed file attachments, images, quotes and narrow width.
• Existing composer, attachment and conversation journeys stay green.

Separate follow-ups from the template audit

Artifact turn → panel flow

ArtifactRecord already carries turnId, but the transcript does not surface the artifact at the turn that produced it. The Astryx template renders an in-message ClickableCard that opens the corresponding side panel, and switches to a fullscreen Dialog at narrow width. Maka currently requires users to discover the artifact in the Files workbar, whose narrow layout is capped at 42dvh.

This is a separate product flow spanning artifact subscription, turn projection, workbar selection and narrow presentation; it should not be folded into the remaining token-rendering slice.

Conversation chronology

Long-lived sessions have no date dividers, and assistant timestamps are not rendered. This is a lower-priority, independent transcript concern.

Deliberate differences from the template

These are not gaps:

• Maka keeps balanced/compact chat density instead of the template's spacious density.
• Assistant avatars remain omitted.
• Localized Maka timestamp formatting remains instead of adopting Astryx Timestamp.
• group="first" / group="last" remains unused because Maka has no consecutive-user-message surface.
• The workbar remains a shared Tasks / Browser / Files / Quote surface rather than an artifact-only panel.

[Astro-Han]

Claiming the remaining sent-reference and attachment-hierarchy slice. I’ll keep workspace @ mentions as plain text, derive sent /skill:<id> tokens from the shared Core grammar, and replace sent non-image attachment cards with compact Astryx Tokens while preserving file type, name, and size. Images, quotes, and persistence contracts remain unchanged. I’ll cover the behavior with focused render tests and Storybook states.